Tools Reference

The primary discovery tool. Always use before Grep or Glob. Returns ranked results with file locations and surrounding context. Supports TF-IDF code search, embedding-based semantic search, file discovery, and exact regex search.

Examples

# Find code by content
c3_search(query='session snapshot restore', action='code')

# Find files by name/path
c3_search(query='hook files in cli/', action='files')

# Semantic similarity search
c3_search(query='code that handles authentication expiry', action='semantic')

# Exact regex match
c3_search(query='class.*Manager', action='exact', top_k=10)

# With auto-prefetch of top results
c3_search(query='memory consolidation', action='code', prefetch=True)

Read specific symbols (functions, classes, methods) or exact line ranges from a file. Always use after c3_compress to get the line map. Never read entire files.

Examples

# Read specific symbols
c3_read(file_path='services/session_manager.py', symbols=['SessionManager.save', 'SessionManager.restore'])

# Read by line range (from compress map)
c3_read(file_path='cli/c3.py', lines='660-720')

# Read a standalone function
c3_read(file_path='services/memory.py', symbols=['recall_facts'])

Returns a compact structural summary of one or more files. Use before c3_read to understand file structure and get the line numbers needed for targeted reads. Supports batch (comma-separated paths).

Examples

# Map a single file
c3_compress(file_path='cli/mcp_server.py', mode='map')

# Map multiple files in one call
c3_compress(file_path='services/memory.py,services/agents.py', mode='map')

# See recent changes
c3_compress(file_path='cli/c3.py', mode='diff')

# Quick bug scan
c3_compress(file_path='services/embedding_index.py', mode='bug_scan')

# Knowledge-graph overview (requires codebase-memory-mcp installed)
c3_compress(file_path='.', mode='ast')

Filters noisy terminal output, log files, or JSONL data to return only relevant lines. Use whenever command output exceeds ~10 lines. Supports inline text or file path input.

Examples

# Filter inline terminal output
c3_filter(text="<pytest output with 200+ lines>")

# Filter a log file for errors
c3_filter(file_path=".c3/sessions/session_042.json", pattern="error|fail")

# Filter build output
c3_filter(text="<webpack build output>", pattern="warning|error")

The only way to edit files in C3. Validates the old_string match, applies the patch, writes the file, and logs the change to the edit ledger. Supports single edits and batched edits to the same file. Can be called in parallel for different files.

Single edit

c3_edit(
  file_path='services/auth.py',
  old_string='return token.expiry > now',
  new_string='return token.expiry > now + CLOCK_SKEW',
  summary='Add clock skew buffer to token expiry'
)

Batch edits to same file

c3_edit(
  file_path='core/config.py',
  edits=[
    {"old_string": "DEBUG = True",      "new_string": "DEBUG = False"},
    {"old_string": "LOG_LEVEL = 'DEBUG'", "new_string": "LOG_LEVEL = 'WARNING'"}
  ],
  summary='Production config hardening'
)

Runs the appropriate native syntax checker for each file type. Supports comma-separated batch validation. Always call after c3_edit and before reporting done. If pyright (Python) or tsc (TypeScript) is on PATH, also runs a deep type check and reports type errors as advisory warnings alongside the PASS result.

Examples

# Single file
c3_validate(file_path='services/memory.py')

# Batch (runs in parallel)
c3_validate(file_path='cli/c3.py,cli/mcp_server.py,services/agents.py')

Supported file types

Finds every file that references a symbol (function, class, variable) before you rename or remove it. Uses git grep for speed with a pure-Python fallback. Groups results by file, scores risk (SAFE / LOW / MEDIUM / HIGH), and in unstaged mode overlays which affected files have uncommitted changes.

Examples

# Check blast radius before renaming a function
c3_impact(target='handle_memory', file_path='cli/tools/memory.py')

# Which affected files also have uncommitted changes?
c3_impact(target='MemoryStore', mode='unstaged')

# Safe to remove? (check before deleting)
c3_impact(target='_legacy_compress')

Risk levels

Run a shell command through C3 with structured returns (exit_code, stdout, stderr, duration_ms), hard timeout + taskkill /F /T on Windows, auto-filter of long stdout, and automatic edit-ledger entries for git-mutating commands. Use for tests, git, builds, and one-shot scripts. Native Bash remains the fallback for interactive / TTY commands (gh pr create with editor, ollama run).

Examples

# Run tests — exit_code propagates, long output is filtered
c3_shell(cmd='pytest tests/test_c3_shell.py -v')

# Git mutation — affected files auto-recorded in the edit ledger
c3_shell(cmd='git commit -m "wire c3_shell"')

# Build with a longer timeout
c3_shell(cmd='npm run build', timeout=300)

Safety classification

The blocklist is a best-effort guard against the most catastrophic commands — not a sandbox. c3_shell runs arbitrary commands by design; for an intentionally dangerous command, use native Bash with explicit approval.

Manages the session lifecycle. Use log to record decisions, snapshot before /clear, restore to recover after /clear, and compact for a one-step restart. Session data persists in .c3/sessions/.

Actions

Examples

# Log a decision
c3_session(action='log', data='Chose Redis over memcached — TTL support needed', reasoning='Session persistence required')

# Before /clear
c3_session(action='snapshot')

# After /clear
c3_session(action='restore')

# One-step restart
c3_session(action='compact')

Persistent key-fact store that survives /clear and session restarts. Use recall at session start to recover context. Facts are stored with salience scores and auto-decayed over time. Supports semantic recall, explicit query, and manual management.

Actions

Examples

# Session start — recall relevant facts
c3_memory(action='recall', query='authentication token system', top_k=5)

# Add a new fact
c3_memory(action='add', fact='[architecture] JWT tokens use RS256 — public key in /etc/c3/jwt.pub', category='architecture')

# Save a convention
c3_memory(action='add', fact='[convention] All new API handlers must call audit_log() before returning', category='convention')

# Verify facts are still accurate
c3_memory(action='ground')

# List all architecture facts
c3_memory(action='list', category='architecture')

Project and session status dashboard. Check token budget, server health, pending notifications, and active session summary.

Examples

c3_status(view='budget')           # Token budget remaining
c3_status(view='health')           # MCP server + services health
c3_status(view='notifications')    # Pending alerts (budget warnings, etc.)
c3_status(view='sessions')         # Recent sessions list

Delegates tasks to local or remote AI backends to save Claude tokens on routine work (summarization, routing, simple Q&A). Supports automatic backend selection based on task type.

Examples

# Delegate summarization to local Ollama
c3_delegate(task='Summarize what this function does', context='<function code>', backend='ollama', task_type='summarize')

# Auto-route based on task type
c3_delegate(task='What is the purpose of this config key?', context='<config snippet>', backend='auto')

Executes compound multi-step workflows using multiple C3 tools in sequence. Useful for common patterns like reviewing changes, preparing context, or running a preflight check.

Available workflows

Examples

# Run a preflight before starting work
c3_agent(workflow='preflight', context='starting auth refactor')

# Prepare context for a specific area
c3_agent(workflow='prepare_context', scope='services/memory.py,services/agents.py')

# Review what changed recently
c3_agent(workflow='review_changes')

# Deep investigation
c3_agent(workflow='investigate', context='why does session restore fail after compact?')

Access the edit ledger — a persistent append-only log of all file changes made through c3_edit. Provides history, version diffing, stats, and tagging. The ledger is also enriched in the background by the EditLedgerEnricherAgent. Since v2.35.0, each entry is stamped with the git branch and HEAD it was made on, and history can be filtered by branch.

Actions

Examples

# Show recent edit history
c3_edits(action='history')

# Version history for a specific file
c3_edits(action='versions', file='services/memory.py')

# Ledger stats
c3_edits(action='stats')

# Edits made on a specific branch
c3_edits(action='history', branch='feature/x')

Connect to a self-hosted enterprise Bitbucket server and operate on it. Tokens live in the OS keyring (Windows Credential Manager / macOS Keychain / Linux Secret Service); only a non-secret index of accounts and the active-account pointer is written to .c3/config.json. Project key + repo slug fall back to the configured defaults.

Setup: c3 bitbucket login --url <URL> (interactive PAT prompt), then c3 bitbucket set-default --project PROJ --repo my-repo. See the Bitbucket integration guide for the full action reference, Hub UI tour, audit-trail integration, and troubleshooting.

Actions

Examples

# Connection probe + active account info
c3_bitbucket(action='status')

# List open PRs in the default repo
c3_bitbucket(action='list_prs', state='OPEN')

# Open a PR
c3_bitbucket(action='create_pr',
             title='Add Bitbucket integration',
             from_branch='feat/bitbucket',
             to_branch='main',
             reviewers='alice,bob')

# Approve and merge — version is fetched automatically
c3_bitbucket(action='approve_pr', pr_id=42)
c3_bitbucket(action='merge_pr', pr_id=42)

Audit trail: mutating actions (merge_pr, create_branch, delete_branch, webhook writes, etc.) are appended to the C3 edit ledger so the local audit log covers platform-side state changes too.

Reach outside the current workspace. C3 keeps a global registry of installed projects (~/.c3/projects.json); c3_project lists/scans them and proxies the core C3 operations against any one — building and caching a full runtime per target project on demand. Name the target by registered name or absolute path (a .c3 directory is required).

Write safety: read ops run freely; mutating ops (edit, shell, and memory add/update/delete) are refused unless you pass allow_write=true, and every foreign mutation is recorded on the target project's activity log and edit ledger.

Actions

Examples

# Which projects have C3 installed?
c3_project(action='list')
c3_project(action='scan')              # also finds unregistered .c3 dirs nearby

# Search / read inside another project
c3_project(action='search', project='SafeMirror', query='token bucket')
c3_project(action='read', project='SafeMirror', file_path='core/limiter.py', symbols='RateLimiter')

# Memory recall from another project's fact store
c3_project(action='memory', project='Sentinel', mem_action='recall', query='auth flow')

# Guarded write — the edit lands in the target project's ledger
c3_project(action='edit', project='Sentinel',
           file_path='README.md',
           old_string='v1', new_string='v2',
           allow_write=true)

Sub-action params: search_action (code/files/semantic/…), mem_action (recall/index/fetch/add/…), and edits_action (history/versions/stats) pick the operation for those verbs; scan_roots (comma-separated) overrides where scan looks.