Cosmos CLI reference

The cosmos command is the terminal surface for local MCP auto-connect and project lesson hooks. Use it when you want to inspect or repair AI tool connections without opening the desktop app.

Install the CLI shim

From a source checkout, install the command into ~/.local/bin:

./scripts/install-cosmos-cli.sh

Then verify it is available:

which cosmos
cosmos status

If ~/.local/bin is not on your PATH, add it to your shell profile and reopen the terminal.

Scan AI tools

cosmos scan is read-only. It scans known AI tool config locations and reports whether each tool is connected to the Cosmos MCP server.

cosmos scan
cosmos scan --json

Use --json when a script or support workflow needs machine-readable output.

Connect Cosmos MCP

cosmos connect writes the Cosmos MCP entry into supported AI tool configs.

cosmos connect
cosmos connect --all
cosmos connect --tool cursor
cosmos connect --tool vscode
cosmos connect --tool zed
cosmos connect --json

Default behavior is the same as --all: Cosmos scans every supported tool and wires tools that are detected but not connected.

--tool <id> explicitly wires one tool. This path can create that tool's MCP config file when the file is missing, matching the desktop app's install button.

Supported tool IDs:

claude_desktop
claude_code
cursor
cline
windsurf
antigravity
antigravity_cli
continue
vscode
zed
roo_code

After connecting a tool, restart that AI app or session so it reloads its MCP configuration.

Check status

cosmos status shows the compact auto-connect summary.

cosmos status
cosmos status --json

The human output includes whether auto-connect is enabled, when the last scan ran, whether the Cosmos MCP launcher resolved, and how many tools are connected.

Manage lesson hooks

cosmos hooks installs, removes, or checks the Cosmos git post-commit lesson hook. The hook does not block commits; it only prints a reminder when a commit message looks like a bug fix.

cosmos hooks install --path ./my-project
cosmos hooks uninstall --path ./my-project
cosmos hooks status --path ./my-project
cosmos hooks status --json

The hook is marker-delimited, so uninstall removes only the Cosmos-managed block and preserves user-owned hook lines.

Troubleshooting

cosmos: command not found

Install the shim and confirm the target directory is on PATH:

./scripts/install-cosmos-cli.sh
which cosmos

No module named 'core'

Use the current launcher from the Cosmos repo. It resolves symlinks and sets PYTHONPATH automatically. Re-run the shim installer if an older local copy is on your PATH.

Tool connected but AI does not show Cosmos tools

Restart the AI app or the current AI session. Most MCP clients read config only on startup. Then verify with that tool's MCP status command, such as /mcp in Claude Code.