@momentalos/cli

Momental CLI tools: code intelligence indexer and agent listener daemon.

Installation

npm install -g @momentalos/cli

Or use without installing:

npx -p @momentalos/cli momental-indexer --help
npx -p @momentalos/cli momental-agent --help

Requires Node.js 20+.

Quick start

# Index your codebase
momental index --dir . --api-key mmt_YOUR_KEY --name my-repo

# Start the agent listener (receives tasks assigned in Momental)
momental agent

# Or use the named bins directly
momental-indexer --dir . --api-key mmt_YOUR_KEY
momental-agent

momental-indexer

Parses your codebase and submits a symbol graph to Momental's code intelligence service. Enables code_search, code_deps, code_blast, code_diff_impact, code_tests, code_tour, and all other MCI tools.

momental-indexer \
  --dir . \
  --api-key mmt_YOUR_KEY \
  --name my-repo \
  --ts-calls \
  --ts-tests \
  --git-cochange \
  --git-sha "$(git rev-parse HEAD)"

Flags

| Flag | Description | |------|-------------| | --dir <path> | Root directory to index (default: .) | | --api-key <key> | Momental API key (mmt_*) — or set MOMENTAL_API_KEY | | --name <name> | Repository name shown in Momental (default: directory name) | | --ts-calls | Index call graph edges via TypeScript compiler (auto-detected if tsconfig.json exists) | | --ts-tests | Index test file → source file relationships (auto-enabled) | | --ts-di | Index NestJS/Angular constructor injection edges (auto-detected) | | --git-cochange | Index files that change together historically (git log) | | --git-sha <sha> | Record commit SHA for incremental re-index detection | | --incremental-files <f> | Re-index only specific changed files (comma-sep, or - for stdin) | | --exclude <paths> | Comma-separated dirs to skip, relative to --dir (e.g. assets/,docs/legacy/) | | --repo-id <id> | Existing repo ID for reindex (skips registration) | | --lang <lang> | Language hint: typescript (default), python, go, javascript, swift | | --dry-run | Parse only — do not submit to Momental | | --quiet, -q | Suppress non-error output (useful for CI pipelines) | | --version | Print version and exit | | --help | Show help |

Environment variables

| Variable | Description | |----------|-------------| | MOMENTAL_API_KEY | API key (alternative to --api-key) | | MOMENTAL_MCP_URL | MCP endpoint (default: https://mcp.momentalos.com/mcp) | | MOMENTAL_AGENT_ID | Agent ID for coding-tool keys (find in .mcp.json) |

CI usage (GitHub Actions)

- name: Index codebase
  run: |
    npm install -g @momentalos/cli
    momental-indexer \
      --dir . \
      --api-key "${{ secrets.MOMENTAL_API_KEY }}" \
      --name my-repo \
      --ts-calls \
      --ts-tests \
      --git-cochange \
      --git-sha "$(git rev-parse HEAD)"

momental-agent

Runs the Momental agent listener daemon. Connects outbound to the Momental relay over WebSocket and spawns claude Code sessions when tasks are assigned to your agent.

No open ports, domain, or tunnel required — outbound WSS connection only.

momental-agent

Setup

Automatic (recommended): Run momental_agent_setup in Claude Code with the Momental MCP connected. It writes ~/.momental/config.json and starts the listener.

Manual: Create ~/.momental/config.json:

{
  "apiKey": "mmt_YOUR_KEY",
  "agentId": "your-agent-slug",
  "workingDir": "/path/to/your/project",
  "agentMode": "single",
  "mcpConfig": {
    "mcpServers": {
      "momental": {
        "type": "http",
        "url": "https://mcp.momentalos.com/mcp/v2",
        "headers": { "Authorization": "Bearer mmt_YOUR_KEY" }
      }
    }
  }
}

Then run from your project root:

cd /path/to/your/project && momental-agent

Expected output:

[relay] Connecting to Momental relay...
[relay] Connected — ready to receive tasks
[relay] Authenticated as agent: your-agent-slug

Environment variables

| Variable | Description | |----------|-------------| | MOMENTAL_API_KEY | Override API key from config |

Flags

| Flag | Description | |------|-------------| | --config <path> | Override config file location (default: ~/.momental/config.json) |

Run as a daemon (macOS — launchd)

First, find the actual bin path:

which momental-agent
# e.g. /usr/local/bin/momental-agent  or  /opt/homebrew/bin/momental-agent

Create ~/Library/LaunchAgents/com.momental.agent.plist, replacing the path with the output above:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.momental.agent</string>
  <key>ProgramArguments</key>
  <array>
    <!-- replace with output of: which momental-agent -->
    <string>/usr/local/bin/momental-agent</string>
  </array>
  <key>WorkingDirectory</key>
  <string>/path/to/your/project</string>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/momental-agent.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/momental-agent.log</string>
</dict>
</plist>

# Find the momental-agent bin path:
which momental-agent

# Load (starts immediately and on every login):
launchctl load ~/Library/LaunchAgents/com.momental.agent.plist

# Stop:
launchctl unload ~/Library/LaunchAgents/com.momental.agent.plist

# View logs:
tail -f /tmp/momental-agent.log

Run as a daemon (Linux — systemd)

First, find the actual bin path: which momental-agent

Create ~/.config/systemd/user/momental-agent.service, replacing the ExecStart path:

[Unit]
Description=Momental agent listener
After=network.target

[Service]
Type=simple
# Replace with output of: which momental-agent
ExecStart=/usr/local/bin/momental-agent
WorkingDirectory=/path/to/your/project
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=default.target

systemctl --user daemon-reload
systemctl --user enable --now momental-agent

# View logs:
journalctl --user -u momental-agent -f

Security note — spawned agent permissions

The listener spawns Claude Code with --dangerously-skip-permissions. This means the agent can read, write, and execute files within your workingDir without per-action confirmation. Only run the listener in project directories you trust, and only with API keys from your own Momental workspace.

Shell completion

# bash
momental completion bash >> ~/.bash_profile && source ~/.bash_profile

# zsh
momental completion zsh >> ~/.zshrc && source ~/.zshrc

# fish
momental completion fish > ~/.config/fish/completions/momental.fish

Updating

npm install -g @momentalos/cli@latest

Check current version:

momental --version
momental-indexer --version
momental-agent --version

Version policy

@momentalos/cli follows semantic versioning independently of the bundled component versions. The CHANGELOG documents which indexer/agent versions each package release includes. Major version bumps (1.x -> 2.x) indicate breaking CLI changes and will include a migration guide.

Troubleshooting

[relay] Config not found Run momental_agent_setup in Claude Code, or create ~/.momental/config.json manually (see Setup above).

claude not found in PATH Install Claude Code: npm install -g @anthropic-ai/claude-code, then restart the listener. If already installed in a non-standard location, ensure its directory is in your PATH.

WebSocket connection refused / 401 Your API key may be invalid or expired. Check ~/.momental/config.json and rotate the key in Momental Settings → Team → Developer.

Tasks assigned but agent not spawning Check that workingDir in ~/.momental/config.json exists and is readable. Check task logs: tail -f ~/.momental/logs/<taskId>.log

Indexer hangs on large repos Add --exclude node_modules/,dist/,build/ to skip generated directories. For TypeScript type-checking (--ts-calls), ensure TypeScript is installed in the repo (npm install typescript or pnpm add typescript).

Python/Go/Swift symbols show but 0 edges (or very few) The indexer's per-language coverage log at the end of each run shows this as a ⚠ hint. Fix:

• Python: install python3 (brew install python or apt install python3) — unlocks AST-based cross-file CALLS + EXTENDS.
• Go: install go (brew install go or from golang.org) — unlocks AST-based cross-package CALLS.
• Swift: no AST path exists; v3.4.0+ emits regex-based same-file CALLS (confidence 0.5). Cross-file Swift calls are not supported. Without these tools, v3.4.0+ still emits regex-based same-file CALLS — better than zero, but AST is recommended for max graph quality.

momental-indexer: No Momental API key found v1.4.0+ auto-discovers your key from: --api-key flag → $MOMENTAL_API_KEY → .mcp.json (walked up to home) → ~/.claude.json → ~/.momental/config.json. If all five fail, generate a key at Settings → API Keys and pass --api-key mmt_... or set the env var.

Your API key is revoked / Invalid token The indexer now prints which config held the stale key. Generate a new key at Settings → API Keys, then either update that file or pass --api-key <new_key> directly. If your .mcp.json has a valid key, copy that into the stale config to resync.

Security

• Scripts are published with SLSA provenance — verify with npm audit signatures @momentalos/cli
• API key is read from ~/.momental/config.json (mode 0600, set by momental_agent_setup)
• The indexer transmits only: symbol names, signatures truncated at the first {, docstrings, line numbers — no source code
• The indexer writes ~/.momental/py-extractor.py on first run (embedded Python AST helper for Python codebases). This file contains no secrets.
• The listener connects outbound over WSS — no inbound ports required