### Install and Run MCP Server

Source: https://github.com/cranot/roam-code/blob/main/README.md

Install the MCP server with the necessary extras and start it. This command installs the package with MCP support and then launches the MCP server.

```bash
pip install "roam-code[mcp]"
roam mcp
```

--------------------------------

### Initial Project Setup with roam-code

Source: https://github.com/cranot/roam-code/blob/main/llms-install.md

After installing, initialize your project to set up the codebase index, fitness rules, and CI workflow. Run `roam health` for a sanity check and `roam understand` for a codebase tour.

```bash
cd /path/to/your/project
roam init             # index + fitness rules + CI workflow (creates .roam/)
roam health           # 0-100 sanity check
roam understand       # one-screen tour of the codebase
```

--------------------------------

### Install Roam Plugin Example Locally

Source: https://github.com/cranot/roam-code/blob/main/dev/example-plugin/README.md

Install the plugin in editable mode to test it against the host repository. This allows you to use Roam commands to inspect the plugin's status.

```bash
pip install -e dev/example-plugin/

roam plugins list              # should list "example"
roam plugins info example
roam plugins doctor            # no errors
```

--------------------------------

### Install MCP Extra and Initialize Roam

Source: https://github.com/cranot/roam-code/blob/main/templates/distribution/landing-page/docs/mcp-usage.html

Install the Roam MCP extra and initialize the project index. This is a one-time setup step before the first MCP call. Initial indexing can take time and is performed manually to avoid exceeding MCP call timeouts.

```bash
pip install "roam-code[mcp]"   # Python 3.10+; pulls fastmcp + tree-sitter
cd /path/to/repo
roam init                       # creates .roam/index.db + fitness rules + CI workflow
roam health                     # verify the index is healthy (0-100 score)
roam mcp-setup                  # write the per-client MCP config snippet
```

--------------------------------

### Clone and Install Roam Code Project

Source: https://github.com/cranot/roam-code/blob/main/README.md

Steps to clone the repository, navigate into the project directory, and install development dependencies including testing tools. Ensure all tests pass after installation.

```bash
git clone https://github.com/Cranot/roam-code.git
cd roam-code
pip install -e ".[dev]"   # includes pytest, ruff
pytest tests/              # all test cases must pass
```

--------------------------------

### Install Log Excerpt

Source: https://github.com/cranot/roam-code/blob/main/docs/fresh-install-smoke.md

Shows a snippet of the installation log, highlighting the download and successful installation of the roam-code package and its dependencies. This confirms the package was installed correctly.

```text
Downloading roam_code-13.2-py3-none-any.whl (3.1 MB)
...
Successfully installed aiofile-3.11.1 ... roam-code-13.2 ... fastmcp-3.3.1
```

--------------------------------

### Example Commit Messages

Source: https://github.com/cranot/roam-code/blob/main/CONTRIBUTING.md

Illustrates the correct format for commit messages, including type and imperative summary. Use these examples as a guide for your own contributions.

```git
feat: add roam stale-refs --attest for in-toto v1 attestations
fix: skip changelog.html in linkcheck (auto-rendered, contains examples)
docs: consolidate to roam-code.com, disable github pages
refactor: collapse two adjacent provider classes in stale-refs hints
ci: render changelog.html on every push
```

--------------------------------

### Install and Initialize Roam-Code

Source: https://github.com/cranot/roam-code/blob/main/skills/roam/SKILL.md

Install the roam-code package and initialize it within your project directory to create a local index database.

```bash
pip install roam-code   # or: pipx install roam-code
cd <project-root>
roam init               # indexes codebase, creates .roam/index.db
```

--------------------------------

### Start MCP Server

Source: https://github.com/cranot/roam-code/blob/main/templates/distribution/landing-page/docs/command-reference.html

Starts the Multi-Agent Coordination Protocol (MCP) server using stdio transport.

```bash
roam mcp
```

--------------------------------

### Install and Initialize Roam Code Compiler

Source: https://github.com/cranot/roam-code/blob/main/README.md

Install the Roam Code package and initialize it within your repository. This setup is required before integrating with tools like Claude Code.

```bash
pip install "roam-code[mcp]"
cd your-repo && roam init
```

--------------------------------

### Install Roam Code from Source

Source: https://github.com/cranot/roam-code/blob/main/README.md

Installs Roam Code directly from its GitHub repository using pip.

```bash
pip install git+https://github.com/Cranot/roam-code.git
```

--------------------------------

### Install Roam Code and Initialize

Source: https://github.com/cranot/roam-code/blob/main/templates/distribution/landing-page/index.html

Install the Roam code package with MCP support and initialize the system. This command is typically run once to set up Roam for use with AI agents.

```bash
pip install "roam-code[mcp]" && roam init
```

--------------------------------

### Install Local Pre-commit Hooks

Source: https://github.com/cranot/roam-code/blob/main/CONTRIBUTING.md

Install local pre-commit hooks for fast-fail count-drift checks and Co-Authored-By rejection. CI runs these checks independently.

```bash
pre-commit install                            # pre-commit stage: count-drift
pre-commit install --hook-type commit-msg     # commit-msg stage: no-coauthor
```

--------------------------------

### Add New Control Entry Example (YAML)

Source: https://github.com/cranot/roam-code/blob/main/templates/audit-report/control-mapping-README.md

Example of a control entry in YAML format, demonstrating required fields like control_id, source_framework, claim, required_evidence, evidence_types, surface, wording_guard, query, pass_condition, and export_text. Use this structure when defining new controls.

```yaml
- control_id: AI_AGENT_RECORD_KEEPING
  source_framework: eu_ai_act_art_12
  claim: Each AI-agent action is recorded with timestamp and actor.
  required_evidence:
    - runs.event.timestamp
    - runs.event.agent
    - runs.event.action
  evidence_types:
    - actor_refs
    - run_ids
    - audit_trail
  surface:
    - governance-pack
    - pr-replay
  wording_guard: "maps to"
  query: |
    SELECT run_id, agent, action, ts
    FROM runs_events
    WHERE run_id = :run_id
    ORDER BY seq;
  pass_condition: all_required_present
  export_text: >-
    Roam's run ledger maps to EU AI Act Article 12 record-keeping by
    capturing timestamp, actor, and action for every recorded agent event.
  notes: |
    Today the ledger is loaded via `roam --json runs show <run_id>`; the
    on-disk bundle (referenced from sibling controls) lives at
    `.roam/pr-bundles/<run_id>.json`.
```

--------------------------------

### Install Roam Code CLI

Source: https://github.com/cranot/roam-code/blob/main/templates/distribution/landing-page/setup.html

Use this command to install the Roam Code CLI and initialize it in your current Git repository. The initialization process indexes your code into a local SQLite database.

```bash
pip install roam-code && roam init
```

--------------------------------

### Onboarding Tour of Key Project Elements

Source: https://github.com/cranot/roam-code/blob/main/skills/roam/SKILL.md

Use this command for an initial onboarding experience, highlighting key symbols, reading order, and entry points within the project.

```bash
roam tour
```

--------------------------------

### Understand Project Stack and Conventions

Source: https://github.com/cranot/roam-code/blob/main/skills/roam/SKILL.md

Run this command the first time you encounter a new repository to get an overview of its tech stack, architecture, health, and conventions.

```bash
roam understand
```

--------------------------------

### First-Run Agent Workflow Example

Source: https://github.com/cranot/roam-code/blob/main/templates/distribution/landing-page/changelog.html

A concise 4-line agent workflow provided at the top of the README for quick execution by new users.

```bash
roam understand "./src"
roam retrieve "./src"
roam context "./src"
roam preflight "./src"
```

--------------------------------

### Load and Test roam_plugin_example_extras

Source: https://github.com/cranot/roam-code/blob/main/dev/example-plugin/README.md

Load the 'roam_plugin_example_extras' module using the environment channel for development. After loading, you can exercise the new command registered by this module.

```bash
PYTHONPATH=dev/example-plugin \
ROAM_PLUGIN_MODULES=roam_plugin_example_extras \
roam plugins list
# Then exercise the new command:
PYTHONPATH=dev/example-plugin \
ROAM_PLUGIN_MODULES=roam_plugin_example_extras \
roam example-greet --name agent
# -> VERDICT: greeted agent
```

--------------------------------

### Initialize Agent and Set Mode

Source: https://github.com/cranot/roam-code/blob/main/templates/examples/agent-change-packet.md

Start the agent and set the editing mode to 'safe_edit'. Initialize the PR bundling process.

```bash
roam runs start --agent "[AGENT_ID]"
roam mode safe_edit
roam pr-bundle init
```

--------------------------------

### Install roam-code CLI

Source: https://github.com/cranot/roam-code/blob/main/llms-install.md

Choose the installation command based on your needs. Use `[mcp]` for the CLI with the FastMCP server, or without for CLI only. `pipx` installs in an isolated environment.

```bash
pip install "roam-code[mcp]"   # CLI + FastMCP server (recommended for agents)
pip install roam-code          # CLI only
pipx install "roam-code[mcp]"  # isolated env
uv tool install "roam-code[mcp]"
```

--------------------------------

### Install Roam Code using uv tool

Source: https://github.com/cranot/roam-code/blob/main/README.md

Installs Roam Code managed by the uv tool. If 'roam' is not found after installation, it suggests running 'uv tool update-shell' and restarting the terminal.

```bash
uv tool install roam-code
```

--------------------------------

### Local Quickstart for Roam Guard PR

Source: https://github.com/cranot/roam-code/blob/main/templates/examples/roam-guard-pr.README.md

Initialize a PR bundle, populate it with agent commands, run the aggregate verdict, and test the CI gate locally. Use `--strict` for CI gate simulation.

```bash
# 1. Initialize a pr-bundle on your feature branch:
roam pr-bundle init --intent "fix auth retry leak"

# 2. (Optional) populate it with the usual agent commands.
#    Each writes a response envelope to .roam/responses/.
roam preflight refresh_token
roam impact refresh_token
roam critique  # if you have a diff staged

# 3. Run the aggregate verdict:
roam guard-pr --format markdown --output verdict.md
cat verdict.md   # reviewer-readable summary

# 4. CI gate locally:
roam guard-pr --strict  # exit 5 if blocked, 4 if needs_review, 0 if pass
```

--------------------------------

### Install Roam in Development Mode

Source: https://github.com/cranot/roam-code/blob/main/AGENTS.md

Install the Roam package in editable mode for development.

```bash
# Install in dev mode
pip install -e .
```

--------------------------------

### Gemini CLI Recommended First Session

Source: https://github.com/cranot/roam-code/blob/main/templates/distribution/landing-page/docs/integration-tutorials.html

Illustrates a first session using Gemini CLI after Roam integration. Useful for semantic search and tracing execution paths.

```bash
roam init
roam search-semantic "authentication flow"
roam trace AuthController AuthRepository
roam test-gaps --changed
```

--------------------------------

### Recipe Structure Example

Source: https://github.com/cranot/roam-code/blob/main/templates/distribution/landing-page/docs/architecture.html

Illustrates the basic structure of a Roam recipe, including inputs, steps, required evidence, gates, report sections, and exports.

```yaml
recipe:
  inputs:            # what the recipe needs (git range, scope, mode)
  steps:             # ordered list of Roam command invocations
  required_evidence: # which fields the packet must contain to close
  gates:             # pass/fail conditions
  report_sections:   # Markdown / structured-output sections
  exports:           # projection list (sarif, in-toto, oscal-like, ...)
```

--------------------------------

### Example Reviewer Markdown Verdict

Source: https://github.com/cranot/roam-code/blob/main/README.md

This is an example of the markdown output generated by `roam guard-pr` that a reviewer might see.

```markdown
## 🛑 Roam Guard verdict: `blocked`

> **0** of **4** required checks ran. **4** missing. Risk: `low`.

### Verdict reasons
- `required_checks_not_run` (×4) — `because=config_file_changed`
  - `lint.make.lint` (detail=['.mcp.json'])
  - `test.make.test` (detail=['.mcp.json'])

### Verification checks
| Status | Command | Why |
|---|---|---|
| 🛑 missing | `lint.make.lint` | config_file_changed |
| 🛑 missing | `test.make.test` | config_file_changed |
```

--------------------------------

### Install Roam Code

Source: https://github.com/cranot/roam-code/blob/main/templates/distribution/landing-page/docs/getting-started.html

Install the Roam code package with optional extras for multi-command processing. Requires Python 3.10+.

```bash
pip install "roam-code[mcp]"
```

--------------------------------

### CI Setup with OSCAL Persistence

Source: https://github.com/cranot/roam-code/blob/main/templates/distribution/landing-page/docs/integration-tutorials.html

Configure `ci-setup` to persist OSCAL artifacts, including control mappings and assessment plan stubs, to the `.roam/oscal/` directory.

```bash
roam ci-setup --with-oscal
```

--------------------------------

### Example McpDecisionReceipt Fragment

Source: https://github.com/cranot/roam-code/blob/main/dev/MCP-SECURITY-POSTURE.md

This JSON fragment shows an example of an McpDecisionReceipt, highlighting the 'redactions' and 'extra' fields, specifically 'redaction_details'.

```json
{
  "redactions": ["secret"],
  "extra": {
    "redaction_details": {"github_pat_classic": 2, "aws_akia": 1}
  }
}
```

--------------------------------

### Install Roam Code with File Watcher

Source: https://github.com/cranot/roam-code/blob/main/templates/distribution/landing-page/docs/troubleshooting.html

Install the file watcher component of Roam Code. This is useful for real-time indexing and updates.

```bash
pip install "roam-code[watch]"
```

--------------------------------

### Install Roam Code with Semantic Search

Source: https://github.com/cranot/roam-code/blob/main/templates/distribution/landing-page/docs/troubleshooting.html

Install the semantic search component of Roam Code. This enables advanced search capabilities.

```bash
pip install "roam-code[semantic]"
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/cranot/roam-code/blob/main/CONTRIBUTING.md

Clone the roam-code repository and install development dependencies, including optional MCP server support.

```bash
git clone https://github.com/Cranot/roam-code.git
cd roam-code
pip install -e ".[dev]"      # core + pytest, pytest-xdist, ruff
pip install -e ".[mcp,dev]"  # also includes fastmcp for MCP server work
```

--------------------------------

### Initialize Roam Index

Source: https://github.com/cranot/roam-code/blob/main/templates/distribution/landing-page/docs/getting-started.html

Initialize Roam in your local repository to create the index database and set up fitness rules and a CI workflow. This is a one-time setup.

```bash
cd /path/to/your/repo
roam init
```