Woods

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

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

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.

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.

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.1.1. 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.1.1, which is not released yet

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

Everything below describes unreleased 2.1.1. 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

For a new default installation, remove the generated db/migrate/*_create_woods_tables.rb migration without running it. Those legacy application tables are unused by the shipped index and storage backends. Keep the generated config/initializers/woods.rb; its defaults are sufficient. Only retain the migration for a deliberate older/custom integration. See Getting started.

bin/rails woods:extract
bin/rails woods:validate
bin/rails woods:stats

Run these where your Rails application can boot. The default output is tmp/woods/; keep this generated directory out of source control.

Adapt this 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.

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

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.

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 requires a supporting gem; check installed capabilities. Older packages run the raw bin/rails woods:watch task under an external restart-capable supervisor.

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.

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 optional Console Server can access live data. Review its setup and security model before enabling it. Report vulnerabilities privately through SECURITY.md.

• 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.

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.

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

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

MIT.