0.0
The project is in a healthy, maintained state
This gem has been renamed to "woods". Install "woods" instead. This shim exists only to notify existing users of the rename.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Dependencies

Runtime

~> 1.0
 Project Readme

Woods

Woods

Give coding agents the Rails context that source files alone leave out.

Gem Version CI License: MIT

Woods boots your Rails application, extracts its resolved structure, and publishes an index that coding agents can query through the Model Context Protocol (MCP). It brings together database schema, associations, callbacks, concerns, routes, and source code so an agent can inspect how Rails assembles your application.

Supports Ruby 3.0+ and Rails 6.0–8.x, using a Ruby version supported by your Rails release. The application must boot and connect to its database. Structural queries need no embedding provider or vector database.

Get started · Documentation · Agent setup · Upgrade from 1.x

What Woods adds

Consider a model whose behavior is spread across Rails, the database, and a concern:

class Order < ApplicationRecord
  include Auditable
  belongs_to :customer
  after_commit :enqueue_receipt, on: :create
end

Woods can give an agent one unit containing its columns and indexes, association metadata, resolved callbacks, and included concern source. Recorded relationships connect that unit to other parts of the application.

An agent can then ask:

Find the Order model, inspect its callbacks and associations, and show its recorded dependents. Cite the indexed evidence and check source code for callers the graph may miss.

Models are one part of the index: Woods also extracts controllers, routes, jobs, mailers, views, components, GraphQL types, service objects, tests, and more. See the extractor reference for coverage and the agent guide for query examples.

Five-minute setup

For agent-led setup, use the agent installation option and its runbook. For a new manual installation, follow the steps below.

Already using Woods? If you are upgrading from 1.x, follow the upgrade guide. For an existing 2.x installation, go directly to retrieval modes, MCP configuration, or the configuration reference. Preserve your initializer, index path, provider settings, and other client entries. Changing only the MCP launch configuration or retrieval mode does not require rerunning the installer or rebuilding the structural index.

Run installation and extraction commands from your Rails application root in its normal development environment. Using Docker? Follow Docker setup first: run those commands inside the application container and use paths visible to the process that runs MCP.

1. Install and configure

These steps are for Woods 2.x. Choose a published 2.x version from RubyGems. If only prereleases are available, use an exact prerelease pin; ~> 2.0 will not select one. Follow the chosen version's tag documentation rather than assuming every feature on main is published. If you choose 1.x, use its tag documentation instead of this quickstart.

This tree documents version 2.2.0. The full history is in the CHANGELOG.

main is the development branch and can run ahead of the latest published gem. The gem badge above shows the latest published version; documentation for a published version lives on its tag.

Version: main documents 2.2.0, which is not released yet

Line Version Documentation
Documented here 2.2.0, unreleased this README and the documentation index
Latest published gem 2.1.0 the v2.1.0 tag

Everything below describes unreleased 2.2.0. It is not available from RubyGems yet. The released constraint stays gem "woods", "~> 2.1".

Add gem "woods", "~> 2.1" to your Gemfile's :development group for the 2.1 line. For an older release or a prerelease, use its published version and matching tag documentation. Then run:

bundle install
bundle exec ruby -rwoods/version -e 'puts Woods::VERSION'
bin/rails generate woods:install

The generator writes config/initializers/woods.rb and nothing else; its defaults are sufficient, and it needs no Active Record. The legacy woods_units/woods_edges/woods_embeddings migration is written only with --legacy-migration, for an older/custom integration that deliberately uses those tables; the shipped index and storage backends never touch them. See Getting started.

2. Set up the watcher and start the app

Add one watcher to your normal development startup. It builds the first index and keeps it current. Pick your mode from the list below and use it in place of puma. Preview the setup, then run the same command without --pretend:

bin/rails generate woods:watch --mode puma --pretend

Choose the mode that matches how you start the app:

  • puma: you run bin/rails server, or a bin/dev that only starts Rails; Puma starts the watcher.
  • procfile: you run an existing Foreman Procfile; the generator adds a woods entry to it.
  • external: Docker Compose, Grove or another supervisor runs the watcher; the generator prints its command.

The startup guide gives the options for each mode. In external mode, add the printed command to your supervisor before you start the app. Then start the app as usual. When the watcher finds no index, it builds the first one in the background under tmp/woods/. In puma mode the app serves requests while it does.

No watcher, or running in CI? Build the index by hand with bin/rails woods:extract instead.

3. Validate

bin/rails woods:extract    # only without a watcher
bin/rails woods:validate
bin/rails woods:stats

With a watcher, run them once the first index is published. The watcher logs to the Rails log (log/development.log by default) and records → generation 1 then. Run these where your Rails application can boot. The default output is tmp/woods/; keep this generated directory out of source control.

4. Connect your MCP client

bundle exec woods-agent-config setup --client claude --scope project --root "$PWD" --plan FILE (then apply FILE) writes a project .mcp.json with no absolute path, so the team can commit it; bin/rails generate woods:install prints the same entry for any client. See managed configuration:

{
  "mcpServers": {
    "woods": {
      "type": "stdio",
      "command": "sh",
      "args": ["-c", "if [ -n \"$CLAUDE_PROJECT_DIR\" ]; then cd \"$CLAUDE_PROJECT_DIR\" || exit 1; fi; exec bundle exec woods-mcp-start --checkout --await-index"]
    }
  }
}

It needs sh where the client runs. On a Woods release without --checkout, or without sh, adapt this per-machine example to your MCP client's project configuration format, using your application path and preserving other server entries. See client configuration locations for guidance:

{
  "mcpServers": {
    "woods": {
      "command": "bundle",
      "args": ["exec", "woods-mcp-start", "./tmp/woods"],
      "cwd": "/absolute/path/to/your-rails-app"
    }
  }
}

Reconnect the client and ask it to call woods_status. Confirm the index path and non-zero unit counts. Then use search to discover a known class and lookup with its identifier and type to inspect it.

The Index Server reads the published index without booting Rails or querying application records. See MCP servers for client-specific configuration and HTTP transport.

If Woods is installed only inside Docker, launch MCP through that container too. Host-side launch needs a host bundle and a host-visible index; see the Docker process and path rule.

Retrieval: with or without embeddings

Exact lookup, pattern search, and graph queries work immediately after extraction. For ranked retrieval through codebase_retrieve, choose a mode:

Mode Setup What it searches
Lexical Set WOODS_RETRIEVAL_MODE=lexical in the MCP process environment and restart the server Published extraction units, ranked by field-aware keyword matching; no provider or embeddings
Semantic (default mode) Configure a local or hosted embedding provider, then run bin/rails woods:embed Embedded code context, ranked by semantic similarity

For the stdio configuration above, add "env": {"WOODS_RETRIEVAL_MODE": "lexical"} inside the woods server entry to choose lexical mode. Confirm the active retriever with woods_status.

To switch back to semantic retrieval, remove the lexical environment override or set WOODS_RETRIEVAL_MODE=semantic, configure the provider and embedding artifacts, then restart the MCP server and verify woods_status. Switching to lexical does not delete existing vectors or provider configuration.

The lexical guide and semantic setup cover configuration, ranking, and response budgets. Lexical matching depends on shared vocabulary; semantic mode requires the configured provider and embedding artifacts.

Keeping the index current

Run one watcher through your normal development startup. It catches up on changes, publishes complete generations, and lets the Index Server refresh on later tool calls. The startup guide covers Puma, existing Foreman workflows, and Docker/Grove supervision. Managed startup needs Woods 2.0 or later. If bin/rails generate woods:watch --help prints the generator's options, your installed Woods has it. With an older Woods, run the raw bin/rails woods:watch task under an external supervisor that restarts it.

Without a watcher, run bin/rails woods:incremental after edits or bin/rails woods:extract for a full rebuild. MCP registration alone does not enable automatic maintenance.

Incremental cost depends on the affected code and relationships; broad changes can cost as much as a full extraction. Semantic embeddings have a separate update step. See Watch daemon, incremental extraction, and source freshness.

Two servers, two trust boundaries

Index Server Console Server
Purpose Inspect extracted code context Query live Rails models and schema
Reads Published index files A booted application and its database
Packaged tools 16; retrieval usable when configured 9; 11 with embedded read tools enabled
Setup The workflow above Deprecated, removed in Woods 3.0; disabled by default

Extraction itself boots and eager-loads your application, so its boot-time behavior still runs. Treat the generated index as confidential application source. Enabling hosted embeddings sends the embedded content to that provider. MCP responses also contain application source, which your client may send to its model provider even when Woods uses lexical retrieval or local embeddings.

The Console Server is deprecated and will be removed in Woods 3.0. Existing setups keep working; new setups should not enable it. See what to use instead. An existing Console setup can still access live data. Review its setup and security model before you rely on it. Report vulnerabilities privately through SECURITY.md.

What the index can and cannot establish

  • It is a snapshot. Check freshness against your working tree before relying on it for a change.
  • Relationships are recorded evidence, not a complete call graph. Arbitrary method-body constant references are not exhaustively indexed. No recorded dependents does not prove that a class has no callers or is safe to delete.
  • A traced flow is not proof of execution. Follow the tool's evidence and limits, and verify behavior in the application when it matters.

Use Woods to locate and connect evidence, then confirm the relevant source and tests. The agent guide describes this workflow.

Let an agent install it

Use the agent setup runbook for a copyable installation prompt and verification checklist. Woods works with MCP-capable clients independently of a specific model or editor.

Claude Code users can optionally install the companion workflows:

/plugin marketplace add lost-in-the/plugins
/plugin install woods-plugin@lost-in-the-plugins

The plugin guides installation, MCP configuration, investigation, repository agent setup, and diagnosis. It is distributed separately from the gem.

Documentation

Task Guide
Install and verify Getting started
Configure clients, Docker, or HTTP MCP servers
Query effectively Agent guide and tool cookbook
Configure Woods Configuration reference
Choose retrieval and storage Retrieval guide and backend matrix
Upgrade from 1.x Upgrade guide
Diagnose a failure Troubleshooting

See the documentation index for all guides and canonical reference pages.

Contributing

Use GitHub issues for bugs and feature requests. Read CONTRIBUTING.md before submitting a pull request; coding agents should also read AGENTS.md.

License

MIT.