rimba init

Initialize rimba in the current repository. Detects the repo root, creates the .rimba/ config directory with settings.toml (team-shared) and settings.local.toml (personal overrides), and sets up the worktree directory.

Agent files — project-tier paths shown here (AGENTS.md, GEMINI.md, .github/copilot-instructions.md, .cursor/rules/rimba.mdc, .claude/skills/rimba/SKILL.md, .windsurf/rules/rimba.md, .clinerules/rimba.md, .pi/skills/rimba/SKILL.md) — can be installed at three tiers. The global tier (-g) writes equivalent per-agent paths under ~/; see Configuration for the full list:

• --agents — project-team level (committed to git)
• --agents --local — project-personal level (gitignored)
• -g / --global — user level (~/) — works outside a git repository

When agent files are installed, rimba also registers itself as an MCP server (rimba mcp) in client config files: .mcp.json, .cursor/mcp.json, ~/.claude.json, ~/.codex/config.toml, ~/.gemini/settings.json, ~/.codeium/windsurf/mcp_config.json, ~/.roo/mcp.json. Use --uninstall with the same flags to remove.

Pi is the one supported agent with no MCP server registration — by design, since Pi’s own philosophy is “No MCP. Build CLI tools with READMEs.” Pi also prompts before trusting a project folder containing project-local resources; its non-interactive modes (-p, --mode json, --mode rpc) never prompt and fall back to defaultProjectTrust, which defaults to "ask" — meaning project-local resources (including .pi/skills/rimba/SKILL.md) are silently ignored in those modes unless you set defaultProjectTrust: "always" or pass --approve. The global tier (~/.pi/agent/) needs no trust decision and is unaffected.

If .rimba/ already exists, config creation is skipped but agent files are still installed or updated. If a legacy .rimba.toml exists, it is migrated into the new directory layout.

Synopsis

rimba init [flags]

Examples

rimba init                        # Initialize config and worktree directory
rimba init --agents               # Also install agent files at project level (committed)
rimba init --agents --local       # Install agent files gitignored (personal)
rimba init -g                     # Install agent files at user level (~/)
rimba init -g --uninstall         # Remove user-level agent files and MCP registration
rimba init --agents --uninstall   # Remove project-team agent files and MCP registration

Common workflows

First-time setup for a team repo

rimba init
rimba init --agents   # Commit agent files so teammates get AI context
git add .rimba/ .github/copilot-instructions.md AGENTS.md
git commit -m "chore: add rimba config and agent files"

Personal setup without affecting teammates

rimba init --agents --local   # Agent files are gitignored

Global user-level install (works in any repo)

rimba init -g   # Installs to ~/ and registers MCP globally

Migrate from legacy .rimba.toml

rimba init   # Detects .rimba.toml and migrates to .rimba/ layout automatically

• --local is not allowed with -g.
• --local without --agents errors with: --local requires --agents.
• --uninstall requires -g or --agents.
• -g / --global and --agents are mutually exclusive.

Flags

Flag	Description
--agents	Install AI agent instruction files at project level
-g, --global	Install agent files at user level (~/) — works outside a git repo
--local	Install agent files gitignored (personal overrides; requires --agents)
--uninstall	Remove agent files and MCP registration (requires -g or --agents)
--personal	Gitignore the entire .rimba/ directory instead of the .rimba/*.local.toml glob

Related commands

• rimba trust · approve committed shell commands after editing settings.toml
• rimba hook · install Git hooks for automated cleanup
• rimba add · create your first worktree