Continuity CLI

Every AI session starts knowing your architecture — decision memory, handoffs, and MCP from the terminal.

Recommended: Most npm users who want cross-session handoff should also install the VS Code extension in the same repo. npm-only without MCP or the extension is day-0 logging, not automatic week-2 handoff.

Command-line workflow for architectural decision tracking, session handoffs, and MCP setup. Works with @continuity/mcp for Cursor, Claude Code, Copilot, Gemini, and Codex — or pair with the extension for passive auto-capture and in-IDE handoff.

License: Proprietary — free tier includes decision logging; Pro unlocks premium CLI features. Pricing. Install @continuity/cli@^3.8.3 (bundles @continuity/[email protected]). Terms.

npm packages

| Package | Role | Install | |---------|------|---------| | @continuity/cli (this package) | Full terminal workflow — continuity bin; installs @continuity/mcp for you | npm install -g @continuity/cli@^3.8.3 | | @continuity/mcp | MCP server for Cursor, Claude Code, Codex, etc. — continuity-mcp bin | Installed with CLI; or npm install -g @continuity/mcp alone | | @continuity/core | Shared business logic (journal, handoffs, search, licensing) — dependency of CLI and MCP | Installed automatically; not for end users | | @continuity/benchmarks | Retrieval benchmark suites — installed on demand by continuity bench | continuity bench list (CLI manages install) |

The Continuity VS Code extension bundles MCP, passive auto-capture, and in-IDE handoff. CLI + @continuity/mcp are the npm path for terminal-first workflows.

Quick Start

npm install -g @continuity/cli@^3.8.3
cd your-project
continuity init

continuity init auto-wires MCP for detected AI clients (Cursor, Claude Code, Codex, etc.). Reload your AI client to connect. Re-run continuity mcp setup anytime to add clients or repair config.

Installed via npm only? Add the extension for week-2 habit

Most npm installers never open the gallery extension — and CLI week-1 return is ~0.6% without it. For auto-capture and full session handoff (not just CLI logging):

From day 2, continuity log will offer to install the extension for you (code --install-extension) — or run it yourself any time. Disable all prompts with continuity config set nudges off or CONTINUITY_NO_NUDGE=1.

1. Install the Continuity extension in VS Code or Cursor (14-day Pro trial, logging stays free after).
2. In the same repo where you ran continuity init, reload the window — handoff and MCP mount from .continuity/ automatically.
3. Optional: continuity recall verify --watch after your first continuity log to confirm cross-session recall.

Same decision journal in .continuity/ — extension and CLI share one memory layer.

npm-only habit loop (no extension)

If you stay on the terminal path, use three commands for week-2 handoff:

continuity init          # once per repo
continuity log "Why X?" "Because Y"
continuity handoff --compact   # before your next AI session

continuity log updates SESSION_HANDOFF.md automatically; continuity handoff refreshes it and copies to clipboard. Run continuity doctor anytime for a red/yellow/green health check (journal, MCP, extension, handoff age, recall).

Claude Code auto-inject: Install the VS Code extension and run setup once — it wires a SessionStart hook under ~/.claude/hooks/ that injects SESSION_HANDOFF.md at every new session. npm-only without the extension: paste handoff manually or add the hook via the extension's MCP setup wizard.

Why Continuity CLI?

Handoff + capture from the terminal — log decisions, generate SESSION_HANDOFF.md, search the journal, and wire MCP without living in an IDE. Pro adds graph, relationships, Dream writes, and premium export (same license as the extension).

Key Features

• 📝 Session handoffs — SESSION_HANDOFF.md with architecture, deltas, commits, and recent decisions injected before the next AI session
• 🧠 Decision journal — append-only .continuity/decisions.jsonl with derived cache
• 🚀 MCP — auto-wired on continuity init + @continuity/mcp bundled for Cursor, Claude Code, Codex, Cline, etc.
• 🔍 Search — keyword and semantic (embeddings) with advanced filters/export
• 🪝 Git hooks — post-commit draft capture + continuity flush promotion
• 💡 Dream Engine — consolidate stale/duplicate/contradictory decisions (continuity dream)
• 🛡️ File protection — block-list patterns for .env, credentials, and custom paths
• 📊 Metrics & convergence — usage stats and multi-client sync tracking
• 🔌 Integrations — Jira/Linear/GitHub webhooks, native tracker CLI, savings statuslines
• 🔗 Knowledge graphs (Pro) — terminal, web (continuity serve), and export — included, not the headline

Installation

Global Installation (Recommended)

npm install -g @continuity/cli@^3.8.3

For MCP workflows, also install @continuity/mcp and activate Pro with continuity license activate — see @continuity/mcp README.

Free vs Pro (CLI)

| Area | Free (always) | Pro / active trial | |------|---------------|-------------------| | Decision logging (log, quick, hooks → drafts) | ✅ Unlimited | ✅ | | Keyword search, sync, init, status, context | ✅ | ✅ | | Semantic search (search:semantic) | ✅ | ✅ | | Git hooks, audit, session notes | ✅ | ✅ | | MCP setup + read tools (via @continuity/mcp) | ✅ | ✅ | | Knowledge graph (graph, visualize) | 🔒 | ✅ | | Relationships (relationships) | 🔒 | ✅ | | Code intelligence (link, links, safety) | 🔒 | ✅ | | Dream writes (dream without --dry-run) | 🔒 after trial | ✅ | | Edit/archive/export premium workflows | 🔒 after trial | ✅ |

Activate: continuity license activate YOUR-KEY · Status: continuity license status

Local Installation

npm install --save-dev @continuity/cli
npx continuity init

From Source

git clone https://github.com/Thiagoscode/continuity
cd continuity/continuity-cli
npm install
npm link

From This Repo Checkout

From the repository root, run the CLI directly without a global install:

node continuity-cli/bin/continuity.js --help
node continuity-cli/bin/continuity.js status
node continuity-cli/bin/continuity.js sync --silent

Commands

Run continuity --help for the full list. Core commands are documented below; additional commands are summarized in Extended commands.

continuity init

Initialize Continuity in your project. Creates .continuity/ directory and auto-protects sensitive files.

continuity init

What it does:

• Creates .continuity/ directory
• Initializes empty decision journal (decisions.jsonl) and derived cache
• Auto-protects .env, credentials.json, SSH keys, etc.
• Adds .continuity/ to .gitignore
• Interactive terminal: optional quick-start (log → reload AI client → recall verify --watch)
• Non-interactive / CI: prints continuity recall verify --watch as the next step (no prompts)
• MCP auto-mount: writes client config for Cursor, Claude Code, Copilot (.vscode/mcp.json), Codex, Gemini, etc.
• Git seed: up to 10 architecturally significant commits → searchable decisions (empty journal only)
• Auto-generate: writes CLAUDE.md, AGENTS.md, .cursorrules, and other client instruction files

continuity sync

Generate SESSION_HANDOFF.md with full project context.

continuity sync              # Generate and copy to clipboard
continuity sync --silent     # Generate file only, don't copy

Generated handoff includes:

• 🏗️ Architecture overview
• 📊 Delta (changes since last sync)
• 📁 Project structure
• 🔄 Recent git commits
• 📝 Recent decisions
• 🎯 Currently modified files
• 💡 Tech stack detection

Example workflow:

1. continuity sync
2. Paste SESSION_HANDOFF.md into new AI chat
3. AI instantly understands your project context

continuity handoff

Generate or refresh SESSION_HANDOFF.md for your next AI session (npm habit path).

continuity handoff              # write file + copy to clipboard
continuity handoff --compact      # shorter handoff (~2k tokens)
continuity handoff --open         # open in $EDITOR (or clipboard if unset)
continuity handoff --quiet        # write file only

Use after continuity log when you are not on the gallery extension path. Pair with continuity recall verify --watch to confirm cross-session recall.

continuity doctor

Health check for the npm install path — journal, extension, MCP binary, MCP client config, handoff file age, and recall verification.

continuity doctor

Exit codes: 0 all green, 2 warnings (e.g. extension missing), 1 blocking issues (journal not initialized, MCP missing).

continuity log

Log architectural decisions for future reference.

continuity log                                    # Interactive mode
continuity log "Why Redis?" "Faster than Postgres for caching"

Decision templates:

• Why X over Y? - Technology choices
• How does X work? - Architecture explanations
• What is X for? - Component purposes
• When to use X? - Usage guidelines
• Where is X implemented? - Code locations

Auto-features:

• Extracts technical keywords as tags (redis, postgres, auth, etc.)
• Timestamps all decisions
• Searchable via continuity search

continuity search

Search logged decisions by keyword.

continuity search redis          # Find all decisions mentioning "redis"
continuity search                # Interactive browser

Search matches:

• Decision questions
• Decision answers
• Auto-extracted tags

continuity protect

Manage file protection to prevent AI modification.

continuity protect                    # Interactive manager
continuity protect list               # List protected patterns
continuity protect add .env           # Protect .env file
continuity protect add "*.key"        # Protect glob pattern
continuity protect remove .env        # Unprotect
continuity protect .env --remove      # Unprotect (legacy flag)

Auto-protected files:

• .env, .env.*
• credentials.json, secrets.*
• SSH keys (id_rsa, id_ed25519)
• .npmrc, .pypirc

continuity status

Show current stats and configuration.

continuity status

Displays:

• Total decisions logged
• Recent decisions (last 30 days)
• Protected files count
• Delta tracking status
• Last sync time
• Handoff file status

continuity config

View or update configuration settings.

continuity config                    # Interactive menu
continuity config maxTokens          # Show current value
continuity config maxTokens 12000    # Set max tokens
continuity config deltaMode true     # Enable delta tracking

Available settings:

• maxTokens (1000-50000) - Maximum tokens in handoff (default: 8000)
• deltaMode (true/false) - Show changes since last sync (default: true)

continuity quick

Quick-log a decision using interactive templates (Why X over Y?, How does X work?, etc.).

continuity quick

continuity scan

Scan the project for architectural decisions that haven't been logged yet.

continuity scan           # Scan project
continuity scan --force   # Re-run even if already scanned

continuity generate

Generate AI instruction files from your project's decisions and structure.

continuity generate            # Generate CLAUDE.md, AGENTS.md, .cursorrules, GEMINI.md, copilot-instructions.md
continuity generate --dry-run  # Preview without writing files

continuity search:semantic

Semantic search using AI embeddings for meaning-based matching.

continuity search:semantic "caching strategy"
continuity search:semantic "auth" --limit 5 --min-score 0.5
continuity search:semantic "deployment" --hybrid-weight 0.7   # 0=semantic, 1=keyword

continuity search:advanced

Advanced search with filters, fuzzy matching, and export capabilities.

continuity search:advanced "auth" --tags security,api
continuity search:advanced --after 2026-01-01 --before 2026-04-01
continuity search:advanced "database" --export markdown
continuity search:advanced --fuzzy 0.8 --format json
continuity search:advanced -i   # Interactive selection mode

continuity relationships

Detect and suggest relationships between decisions (supersedes, contradicts, depends-on, related-to).

continuity relationships                          # Analyze all decisions
continuity relationships <decision-id>            # For a specific decision
continuity relationships "auth" --min-confidence 0.5

continuity metrics

View usage metrics, information gain statistics, and decision velocity.

continuity metrics              # Display in terminal
continuity metrics --export     # Export to Markdown file
continuity metrics --top-tags 5 # Show top 5 tags

continuity graph

Build and export the decision knowledge graph.

continuity graph                        # Export as Mermaid (default)
continuity graph -f dot -o graph.dot    # Export as Graphviz DOT
continuity graph -f json                # Export as JSON
continuity graph -f cytoscape           # Export as Cytoscape JSON

continuity serve

Start the web dashboard server for browser-based decision browsing.

continuity serve              # Start on default port 24280
continuity serve -p 3000      # Start on custom port

continuity dashboard

Launch a live monitoring dashboard in the terminal with real-time stats.

continuity dashboard

continuity tui

Launch an interactive terminal UI for browsing and navigating decisions.

continuity tui

continuity timeline

View a decision timeline visualization.

continuity timeline                # ASCII timeline
continuity timeline -i             # Interactive mode
continuity timeline -w 80          # Custom bar width

continuity visualize

Visualize the decision graph directly in the terminal.

continuity visualize            # Full graph
continuity visualize -i         # Interactive mode
continuity visualize -c         # Compact ASCII view

continuity mcp

Manage the MCP (Model Context Protocol) server for AI tool integration.

continuity mcp start           # Start MCP server
continuity mcp stop            # Stop MCP server
continuity mcp status          # Show server status
continuity mcp status --logs   # Status with recent log entries
continuity mcp setup           # Configure AI tools for MCP

continuity dream

Run memory consolidation using the Dream Engine — analyzes decisions for conflicts, redundancy, and staleness.

continuity dream               # Run full consolidation
continuity dream --dry-run     # Preview without making changes
continuity dream --report      # Show last dream report

continuity notes

Manage session notes (goals, blockers, progress).

continuity notes                          # View current session notes
continuity notes update blockers "desc"   # Add a blocker
continuity notes clear                    # Archive notes and start fresh

continuity debt

Track and resolve decision debt (decisions that need revisiting).

continuity debt              # List current decision debt
continuity debt resolve <id> # Mark debt item as resolved

continuity governance

Check governance conflicts and manage decision locks.

continuity governance check "switch to MongoDB"   # Check proposal for conflicts
continuity governance lock                         # View locked decisions
continuity governance reset                        # Reset danger score

continuity hooks

Manage git hooks for automatic decision logging on commits.

continuity hooks install      # Install pre/post-commit hooks
continuity hooks uninstall    # Remove hooks
continuity hooks status       # Show hook installation status

continuity link / continuity links / continuity safety

Code intelligence — link decisions to specific code locations.

continuity link <decision-id> src/auth.ts 42    # Link decision to file:line
continuity links                                 # Show all code-decision links
continuity links src/auth.ts                     # Show decisions linked to a file
continuity safety src/auth.ts                    # Check refactoring safety

continuity license

Manage your Continuity Pro license.

continuity license activate <key>   # Activate a Pro license key
continuity license status           # Show current license status
continuity license info             # Tier comparison and pricing
continuity license deactivate       # Deactivate current license

continuity update

Update an existing decision by ID.

continuity update <id> --question "New question"
continuity update <id> --answer "Updated answer"
continuity update <id> --tags "new,tags"
continuity update <id> --status outdated       # active, outdated, or deprecated

continuity archive

Archive decisions by age or status.

continuity archive --older-than 90             # Archive decisions >90 days old
continuity archive --status deprecated         # Archive deprecated decisions
continuity archive --dry-run                   # Preview without changes

continuity entities

Manage entity extraction from decisions.

continuity entities backfill          # Extract entities from all decisions
continuity entities stats             # Show entity statistics
continuity entities backfill --dry-run # Preview without writing

continuity lint

Lint the decision wiki for quality issues.

continuity lint        # Run all checks
continuity lint -v     # Verbose with details per category

Checks for: contradictions, orphan decisions, stale entries, low-quality answers, duplicates.

continuity report

Generate a topic report from decisions.

continuity report "authentication"                # Summary report
continuity report "database" -f comparison         # Comparison format
continuity report "api" -f timeline                # Timeline format

continuity source

Manage knowledge sources (external documents ingested into decisions).

continuity source ingest <file>    # Ingest a document
continuity source list             # List ingested sources
continuity source get <id>         # Get source details

continuity audit

Audit decision coverage against recent git commits.

continuity audit              # Audit last 7 days
continuity audit -d 30        # Audit last 30 days
continuity audit --auto-log   # Auto-create draft decisions for uncovered commits

continuity echo-chamber

Detect echo-chamber risk — clusters of decisions reinforcing the same conclusion without counter-evidence.

continuity echo-chamber                 # Default analysis
continuity echo-chamber --min-cluster 5 # Only report clusters of 5+

Extended commands

| Command | Purpose | |---------|---------| | continuity context | Compact project context (CLI mirror of MCP get_quick_context) | | continuity task / note / working | Forward tasks and ticket notes via configured webhooks | | continuity bench | Run @continuity/benchmarks suites (list, peer-review, multi-corpus) | | continuity convergence | Cross-client decision sync metrics (status, record, dogfood) | | continuity export | Export decisions to JSON/Markdown with optional PII redaction | | continuity journal compact | Deduplicate append-only journal lines | | continuity journal scrub-pii | Redact emails in the journal (requires --confirm) | | continuity webhook | Manage HTTP webhook fanout (decisions/tasks/notes) | | continuity tracker / credentials | Native tracker credentials (Jira/Linear/GitHub) | | continuity savings | Estimate dollars saved by context injection | | continuity claude-statusline / gemini-savings | Terminal session savings hooks | | continuity capabilities | Run synthetic-memory capability audit (requires Anthropic API key) | | continuity flush | Promote post-commit hook drafts into the journal | | continuity regen-decisions-json | Rebuild decisions.json cache from journal | | continuity repair-causal-edges | Fix mis-oriented causal relationship edges |

File Structure

your-project/
├── .continuity/
│   ├── decisions.jsonl         # Append-only decision journal (source of truth)
│   ├── decisions.json          # Derived cache (regenerated from journal)
│   ├── protected-files.json    # Protected file patterns
│   ├── delta-snapshot.json     # Last sync snapshot
│   ├── SESSION_NOTES.md        # Session goals/blockers (optional)
│   └── config.json             # CLI configuration
├── SESSION_HANDOFF.md          # Generated context (often gitignored)
└── .gitignore                  # Updated to ignore Continuity artifacts

Workflow Examples

Example 1: Starting a New AI Session

# 1. Generate fresh context
continuity sync

# 2. Use @continuity in your AI tool (or paste SESSION_HANDOFF.md)

# 3. AI now knows:
#    - Your project architecture
#    - Recent changes
#    - Past decisions
#    - What you're currently working on

Example 2: Logging a Decision

# Just made a big architectural decision?
continuity log

# Question: Why did we choose PostgreSQL over MongoDB?
# Answer: Need ACID compliance for financial transactions,
#         relational data model fits our domain better,
#         team has more Postgres experience.

# ✅ Decision logged - will appear in future handoffs

Example 3: Project Onboarding

# New team member setup
cd project
continuity init
continuity sync

# Share SESSION_HANDOFF.md with new developer
# They can paste it into their AI tool to understand the project instantly

Example 4: Protecting Sensitive Files

# Prevent AI from modifying production config
continuity protect config/production.yml

# View all protected files
continuity protect

# AI tools will be warned not to modify these files

Advanced Usage

Custom Token Limits

# For larger codebases, increase token limit
continuity config maxTokens 15000
continuity sync

Scripting & CI/CD

# Generate handoff in CI pipeline (no clipboard)
continuity sync --silent

# Check if handoff is up to date
continuity status | grep "Modified: less than"

Multiple Projects

# Each project has its own .continuity/ directory
cd project-A && continuity init && continuity sync
cd ../project-B && continuity init && continuity sync

# Decisions and config are project-specific

Integration with AI Tools

Claude Desktop / Claude.ai

1. Run continuity sync
2. Copy SESSION_HANDOFF.md content
3. Paste into new Claude chat
4. Claude now has full project context

Cursor / GitHub Copilot Chat

1. Run continuity sync
2. Open SESSION_HANDOFF.md in editor
3. Reference in chat: @SESSION_HANDOFF.md
4. AI uses file as context

ChatGPT / Any LLM

1. Run continuity sync
2. Copy SESSION_HANDOFF.md content
3. Paste into chat with: "Please read this project context first"

Troubleshooting

Command not found: continuity

# Ensure global install worked
npm list -g --depth=0 | grep continuity

# Or use npx
npx @continuity/cli init

"Not a git repository"

Continuity requires git for tracking changes and commits.

git init
git add .
git commit -m "Initial commit"
continuity init

Handoff file too large

# Reduce token limit
continuity config maxTokens 5000

# Or use --silent to skip clipboard (large files fail to copy)
continuity sync --silent

Protected files not working

Protected files are tracked in .continuity/protected-files.json. The protection is informational - you must configure your AI tool to respect it.

CLI vs Extension vs MCP

All three surfaces share @continuity/core (journal, handoffs, search, licensing). Choose by workflow, not by "power level."

| Capability | CLI (@continuity/cli) | @continuity/mcp | VS Code extension | |------------|-------------------------|-------------------|-------------------| | Decision logging | ✅ continuity log | ✅ log_decision tool | ✅ Sidebar + auto-capture | | Handoffs / context | ✅ sync, context | ✅ get_quick_context | ✅ Auto-sync + sidebar | | Semantic search | ✅ search:semantic | ✅ MCP search tools | ✅ Sidebar + MCP | | Knowledge graph | ✅ Terminal + serve web UI | ✅ Graph MCP tools | ✅ Interactive D3 webview | | Git hook drafts | ✅ hooks install, flush | — | ✅ + save/session auto-capture | | Passive auto-logging | Manual + hooks | — | ✅ Git + save + session | | MCP server | ✅ continuity mcp wraps same server | ✅ continuity-mcp bin | ✅ Bundled + auto-repair | | MCP client setup | ✅ continuity mcp setup | Manual JSON config | ✅ One-click sidebar | | @continuity in AI chats | ✅ After MCP setup | ✅ | ✅ | | Best for | CI/CD, scripting, terminal-first | MCP-only, no VS Code | Daily VS Code + richest UI |

When to use CLI: no VS Code, automation/CI, server workflows, license activation, journal maintenance, git-hook-driven capture.

When to use @continuity/mcp alone: MCP client already configured; you only need the server binary on PATH.

When to use the extension: VS Code daily driver, passive capture, sidebar editing, interactive graphs, integrated MCP repair.

MCP integration

MCP works from either the CLI or the VS Code extension — both configure the same @continuity/mcp server.

Install

npm install -g @continuity/cli@^3.8.3
continuity mcp setup        # auto-detect clients and write config
# — or configure manually (see @continuity/mcp README)

Supported AI clients

| Client | MCP | Typical usage | |--------|-----|---------------| | Cursor | ✅ | @continuity search for auth decisions | | Claude Code / Claude Desktop | ✅ | @continuity tell me about this project | | OpenAI Codex | ✅ | /mcp to verify, then @continuity … | | Cline / Roo Code | ✅ | @continuity what changed recently? | | GitHub Copilot (MCP) | ✅ | @continuity review decisions | | Windsurf | ✅ | Same MCP config pattern |

Manual MCP config (global install)

{
  "mcpServers": {
    "continuity": {
      "command": "continuity-mcp",
      "args": [],
      "env": {
        "WORKSPACE_ROOT": "/absolute/path/to/your/repo"
      }
    }
  }
}

WORKSPACE_ROOT must be an absolute path. Restart the MCP client after config changes.

Codex users: use /mcp in the TUI to confirm the server is mounted.

Works Well With: Serena

Serena is a complementary MCP server for semantic code navigation. Use both together:

In Claude Code:

@serena find the login function
> Found: login() at src/auth.ts:45

@continuity why did we choose JWT for auth?
> Decision #23: "We chose JWT tokens because..."

@serena show references to login()
> 12 references across 5 files

@continuity what security decisions relate to login?
> Related decisions: rate limiting, password hashing, session management

Continuity = Project memory & decisions Serena = Code navigation & symbol search

Together they provide a complete AI coding experience!

Contributing

Issues and PRs welcome at: https://github.com/Thiagoscode/continuity

License

Proprietary — Copyright © Hackerware. All rights reserved. See LICENSE in this package and Software License Terms.

• Free tier: decision logging, basic search, init/sync, and related core commands.
• Pro: premium commands (semantic search, graphs, code intelligence, dashboards, etc.) require a valid license — continuity license activate YOUR-KEY.
• Do not install @continuity/cli versions below 3.5.0; they are deprecated and may show outdated MIT metadata on npm.

Credits

Built by Hackerware / @Thiagoscode

Questions? Open an issue: https://github.com/Thiagoscode/continuity/issues