Skip to content

Getting started

comindly builds a map of your repositories: what calls what, across repositories and through HTTP routes, queues, topics, buckets and tables, plus what your team recorded about the code. Your coding agent reads that map through MCP; you read it in the terminal and a local web UI.

This page takes you from nothing to an agent that uses comindly, in about ten minutes.

1. Install

Prebuilt binaries for macOS (arm64, x64) and Linux (x64, arm64) are attached to each GitHub release:

curl -LsSf https://raw.githubusercontent.com/sayef/comindly/main/scripts/install.sh | sh
comindly --version

From crates.io, with Rust 1.95 or newer plus protoc and cmake:

cargo install comindly

Or from source:

git clone https://github.com/sayef/comindly && cd comindly && cargo build --release

2. Index your code

The quickest way is the app: comindly app (macOS) or comindly ui --web --open, then Repositories → Scan a folder → tick your repositories → Index now. The same from the terminal:

comindly repos add ../shared-lib ../orders ../payments   # remembered in config.toml
comindly link --index-dir ~/comindly-index                 # each repo's default branch, never your folders

Or one repository, as it is on disk, into the default location (comindly config path shows it):

comindly index .

Several repositories that talk to each other belong in one index, so comindly can connect them:

comindly link ../shared-lib ../orders ../payments --index-dir ~/comindly-index

Everything runs locally. With OPENAI_API_KEY set (or any OpenAI-compatible endpoint), comindly also writes one-line summaries, flow walkthroughs and a style guide; --no-llm turns that off. Re-running link is incremental: only repositories that changed are parsed again.

For a team, build the index in CI into your own bucket (--index-dir s3://bucket/prefix) and let everyone read it; see Team setup.

3. Look around

comindly search "where do we retry HTTP calls" --index-dir ~/comindly-index
comindly explore OrderService.place_order --index-dir ~/comindly-index   # neighbourhood and blast radius
comindly contracts --index-dir ~/comindly-index                         # who serves and who calls what
comindly app --index-dir ~/comindly-index                               # macOS: its own window
comindly ui --web --open --index-dir ~/comindly-index                   # any OS: in the browser

The web UI shows the org map, contracts, the ledger, conventions and internal packages; press ⌘K to search by name or by describing what you are looking for. Its Connect page repeats the next step with your index path filled in.

4. Connect your agent

comindly serves MCP over stdio: the agent starts comindly serve and calls its tools when a question needs them.

claude mcp add --scope user comindly -- comindly serve --index-dir ~/comindly-index

~/.cursor/mcp.json:

{
  "mcpServers": {
    "comindly": { "command": "comindly", "args": ["serve", "--index-dir", "~/comindly-index"] }
  }
}

~/.codex/config.toml:

[mcp_servers.comindly]
command = "comindly"
args = ["serve", "--index-dir", "~/comindly-index"]

.vscode/mcp.json:

{
  "servers": {
    "comindly": { "type": "stdio", "command": "comindly", "args": ["serve", "--index-dir", "~/comindly-index"] }
  }
}

For an index in S3, give the server AWS credentials, for example -e AWS_PROFILE=… -e AWS_REGION=… with claude mcp add, or an env block in the JSON and TOML configs.

Restart the agent and ask it something only a map of the whole codebase can answer:

  • "What breaks in other services if I change the signature of place_order?"
  • "Who calls GET /orders/{id}, and which queue does the order service publish to?"
  • "What should I read before changing PaymentClient.charge?"
  • "Why is this function written this way? Did anyone try something else?"

Using comindly with agents lists every tool with the questions it answers.

5. Optional: hooks

Hooks put what the team recorded in front of the agent without it asking: records about the repository when a session starts, and about a file just before the agent edits it.

comindly init-hooks claude     # prints settings to merge into ~/.claude/settings.json

comindly init-hooks cursor, gemini, codex and generic print the equivalent for other agents.

6. Check your setup

comindly doctor --index-dir ~/comindly-index

It checks the index, the ledger, cloud credentials, hooks, the LLM key, signing and SCIP indexers, and says how to fix what is missing. The web UI's Connect page shows the same checks.

Next