ctxo init
Bootstraps a project for ctxo. Runs four steps:
- Ensures
.ctxo/index/and.ctxo/config.yamlexist. - Generates MCP usage rules for the AI tools you use and registers the ctxo MCP server in their config files. Supported tool ids:
claude-code,cursor,github-copilot,windsurf,antigravity,augment,amazonq,gemini-cli,continue. - Installs the safe-edit guard hook and model-invoked skills (Claude Code and Cursor).
- Offers to install missing language plugins and to install git hooks that re-index on commit and rebuild the SQLite cache on merge.
Requires a git repository (run git init first).
Synopsis
ctxo init [options]Flags
| Flag | Short | Default | Description |
|---|---|---|---|
--yes | -y | false | Non-interactive. Install everything, skip prompts. Combine with --tools to pick tools |
--tools <list> | Comma-separated list of AI tool ids (for example claude-code,cursor). Implies non-interactive | ||
--rules | false | Only regenerate AI tool rule files. Skips index dir, plugins, and git hooks | |
--no-install | false | Skip the language-plugin detection prompt (and the implicit install under --yes) | |
--dry-run | false | Print the files that would be created or modified and exit |
What it writes
| Path | Notes |
|---|---|
.ctxo/index/ | Created if missing (holds per-file JSON indices) |
.ctxo/config.yaml | Default config is dropped if absent. See config reference |
.gitignore | .ctxo/.cache/ appended if not already present |
| AI rule files | Per selected tool: CLAUDE.md, .cursor/rules/ctxo.mdc, .github/copilot-instructions.md, .windsurfrules, AGENTS.md, augment-guidelines.md, .amazonq/rules/ctxo.md, GEMINI.md, .continue/rules/ctxo.md |
| AI MCP configs | Per selected tool: .mcp.json (Claude Code / Cursor / Windsurf / Antigravity / Augment), .vscode/mcp.json (Copilot), .amazonq/mcp.json, .gemini/settings.json, .continue/mcpServers/ctxo.json |
.claude/settings.json | Registers the ctxo gate-hook PreToolUse hook (Claude Code only) |
.claude/skills/ctxo-understand/SKILL.md | Model-invoked skill: orient at task start (Claude Code) |
.claude/skills/ctxo-safe-edit/SKILL.md | Model-invoked skill: blast radius + why-context before edits (Claude Code) |
.claude/skills/ctxo-review-pr/SKILL.md | Model-invoked skill: PR risk via get_pr_impact (Claude Code) |
.cursor/rules/ctxo-understand.mdc | Same skill for Cursor |
.cursor/rules/ctxo-safe-edit.mdc | Same skill for Cursor |
.cursor/rules/ctxo-review-pr.mdc | Same skill for Cursor |
.git/hooks/post-commit | Incremental re-index of changed files (idempotent block, marked # ctxo-start / # ctxo-end) |
.git/hooks/post-merge | Runs ctxo sync after git pull |
Safe-edit guard prompt
When ctxo init detects Claude Code or Cursor, it asks whether to install the safe-edit guard. Answering yes writes the hook entry to .claude/settings.json and copies the three skills. The guard is enabled by default at balanced sensitivity; tune it via gate: in .ctxo/config.yaml:
gate:
enabled: true
sensitivity: balanced # strict | balanced | lenientUse ctxo gate --preview to see which symbols the current sensitivity level would flag before committing to it. See the Safe-Edit Guard guide for the full explanation.
Skills are passive instructions
Skills are markdown files the model reads - they do not execute code. The PreToolUse hook in .claude/settings.json is the only thing that actually blocks an edit. Skills guide the agent toward running get_blast_radius proactively.
Hooks are safe to re-run
The hook installer detects the # ctxo-start marker and leaves existing hooks untouched. You can safely re-run ctxo init to pick up new AI tool rules.
Examples
ctxo init# Pick tools explicitly and install everything without prompts.
ctxo init --tools claude-code,cursor --yes# Refresh AI tool rules after a ctxo upgrade. Don't touch plugins or hooks.
ctxo init --rules# Set everything up but defer plugin installation to a later step.
ctxo init --no-install --yes --tools claude-codectxo init --dry-runExit codes
| Code | Meaning |
|---|---|
0 | Setup completed (or dry-run printed successfully) |
1 | Not a git repository, or unknown tool id passed to --tools |
See also
ctxo install- the plugin installer invoked byinit.ctxo index- the next command to run after setup.- .ctxo/config.yaml reference - customize ignore globs and opt out of stats.