Workflow

The first thing Claude should do at the start of any non-trivial task. This loads relevant facts from the persistent memory store — architecture decisions, conventions, ongoing work, gotchas discovered in prior sessions.

c3_memory(action='recall', query='authentication system refactor')

When to recall

• Start of any multi-step task
• When the task touches a system you've worked on before
• When you suspect there are architecture decisions or gotchas to be aware of

When you can skip

• Trivial one-off tasks (rename a variable, fix a typo)
• Brand new projects with no prior sessions

# Never start with native tools
Grep(pattern='AuthMiddleware')
Glob(pattern='**/*.py')

c3_search(query='AuthMiddleware', action='code')
c3_search(query='*.py auth', action='files')

prefetch=True

Pass prefetch=True to auto-compress the top result files in parallel, saving a round-trip:

c3_search(query='session manager', action='code', prefetch=True)

Reading a whole file wastes tokens. The correct pattern is: compress to get the map, then read only the specific symbols or lines you need.

# Reading entire files
Read(file_path='services/session_manager.py')

# Map → targeted read
c3_compress(file_path='services/session_manager.py', mode='map')
c3_read(file_path='services/session_manager.py', symbols=['SessionManager.save'])

Compress modes

Batch compress

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

Before renaming, removing, or changing the signature of any function or class used across files, run c3_impact to find every call site. A HIGH risk result means all those files need updating in the same edit pass — skipping this step is how silent breakages happen.

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

# Check what's affected AND has uncommitted changes
c3_impact(target='MemoryStore', mode='unstaged')

When to skip

Skip c3_impact when editing purely local symbols (private helpers, inner functions, one-off scripts). Use it for anything in a shared service, public API, or imported across files.

c3_edit does read + patch + write + edit ledger log in one step. It also validates the old_string match before writing. If the literal match fails but the strings differ only by unicode lookalikes (curly quotes, em/en-dashes, NBSP), c3_edit retries with a 1:1 normalized match and tags the response [unicode-normalized].

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

Batching edits to the same file

Use the edits=[] parameter to apply multiple patches to one file in one call:

c3_edit(
  file_path='src/config.py',
  edits=[
    {"old_string": "DEBUG = True",  "new_string": "DEBUG = False"},
    {"old_string": "HOST = 'localhost'", "new_string": "HOST = '0.0.0.0'"}
  ],
  summary='Production config hardening'
)

Parallel edits across files

# Call c3_edit for multiple files in parallel (same message, different files)
c3_edit(file_path='src/a.py', old_string='...', new_string='...', summary='...')
c3_edit(file_path='src/b.py', old_string='...', new_string='...', summary='...')

Any terminal output longer than ~10 lines should be passed through c3_filter to extract only the relevant signal before including it in context.

# Filter raw terminal output
c3_filter(text="<long test output here>")

# Filter a log file
c3_filter(file_path=".c3/sessions/session_001.json", pattern="error|warning")

Always call c3_validate after edits. Never report "done" without validation. A syntax error introduced silently is worse than no change at all. If pyright (Python) or tsc (TypeScript) is on your PATH, C3 also runs a deep type check automatically and surfaces type errors as advisory warnings alongside the PASS result.

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

# Batch — comma-separated (runs in parallel internally)
c3_validate(file_path='services/auth.py,services/session.py,cli/c3.py')

Supported languages

Log a decision

c3_session(action='log', data='Chose JWT over session cookies — easier horizontal scaling')

Snapshot before /clear

Always snapshot before running /clear. This saves the full session state so the next session can restore it.

c3_session(action='snapshot')
# Then in Claude Code: /clear

Auto-snapshot on session end

C3 automatically captures a snapshot when a session ends — including Ctrl+C, natural stop, and max-turn exits. This is handled by a Stop hook (hook_auto_snapshot.py) that fires after Claude's last response.

Installation: Stop hooks are registered automatically by c3 install-mcp. For existing projects, re-run c3 install-mcp to add them. No manual configuration needed.

Manual snapshots are still recommended before /clear for maximum reliability, but the auto-snapshot serves as a safety net.

Restore in new session

c3_session(action='restore')

Compact (one-step restart)

# Snapshot + summary + restore instruction in one step
c3_session(action='compact')