Sessions

nca persists every conversation as a session. Sessions can be resumed, inspected, attached to, and managed through the CLI.

Session Lifecycle

nca (start) → Session Created → Agent Turns → Session Ended
                    ↓                              ↓
              .nca/sessions/<id>.json         .nca/sessions/<id>.events.jsonl
                    ↓                              ↓
              State snapshot                  Full event log

States

Session Storage

Sessions are stored in the workspace under .nca/sessions/:

.nca/sessions/
├── a1b2c3d4.json            # Session state snapshot
├── a1b2c3d4.events.jsonl    # Event log (NDJSON)
├── e5f6g7h8.json
├── e5f6g7h8.events.jsonl
└── ...

State File (.json)

Contains session metadata:

• Session ID and timestamps (created, updated)
• Workspace path and working directory
• Model and provider configuration
• Session status and PID
• Socket path for IPC
• Parent/child session relationships
• Session summary
• Git branch information
• Worktree path (for sub-agent sessions)

Event Log (.events.jsonl)

Append-only NDJSON log of every event in the session:

• Messages sent and received
• Token usage and streaming events
• Tool call starts and completions
• Approval requests and resolutions
• Child session spawns and completions
• Context warnings and compaction events
• Errors and status changes

Each event has a monotonic id and ts (timestamp).

Managing Sessions

List Sessions

nca sessions                           # List recent sessions (default: 20)
nca sessions --limit 50                # Show more
nca sessions --status running          # Filter by status
nca sessions --since-hours 24          # Last 24 hours
nca sessions --search "auth"           # Search by content
nca sessions --json                    # JSON output

Resume a Session

Resume picks up a session with full conversation context:

# Resume by ID
nca resume <session-id>

# Resume with a follow-up prompt
nca resume <session-id> --prompt "continue with the tests"

# Resume with a different model
nca resume <session-id> --model "claude-3-7-sonnet-latest"

# Resume the most recent session (shorthand)
nca -r
nca --resume

Auto-Resume Behavior

By default, when you run nca without any arguments:

1. nca checks .nca/.last_session for the most recent session ID
2. If a valid recent session exists, nca auto-resumes it with a hint to stderr
3. If no valid session exists, a new session starts

Override this:

nca --no-resume    # Always start fresh
nca --resume       # Always resume last session

View Session Logs

nca logs <session-id>              # Dump event log
nca logs <session-id> --follow     # Stream in real-time
nca logs <session-id> --json       # Raw JSON events

Attach to a Running Session

nca attach <session-id>            # Attach to output stream
nca attach <session-id> --json     # JSON event stream

Check Session Status

nca status <session-id>            # Show metadata
nca status <session-id> --json     # JSON output

Cancel a Running Session

nca cancel <session-id>

Interactive Session Switching

In the TUI, use /sessions to open a session picker or press Ctrl+X L:

/sessions                  # Open session picker
/new                       # Start a new session

Session Context Management

Context Compaction

As conversations grow, nca can summarize and compact the context to stay within the model’s context window:

/compact                   # Manually compact context

Automatic compaction is controlled by:

[memory.context]
auto_summarize_threshold = 75    # Trigger at 75% of context window
enable_auto_summarize = true
max_retained_messages = 50

When auto-summarize triggers, nca:

1. Emits a ContextWarning event
2. Summarizes the conversation history
3. Replaces older messages with the summary
4. Emits a ContextCompaction event

Checkpointing

Sessions are checkpointed periodically to prevent data loss:

[session]
checkpoint_interval = 5    # Save every 5 turns

Session Export

Export a session to markdown:

/export

Session Configuration

[session]
history_dir = ".nca/sessions"         # Where sessions are stored
max_turns_per_run = 128               # Max turns before session ends
max_tool_calls_per_turn = 200         # Max tools per single turn
checkpoint_interval = 5               # Checkpoint frequency
last_session_file = ".nca/.last_session"  # Last session pointer
auto_compact_on_finish = false        # Summarize on session end

Background Sessions

Use nca spawn to create sessions that run in the background:

nca spawn --prompt "refactor the auth module"

Spawned sessions:

• Run without interactive input
• Default to accept-edits permission mode
• Can be monitored with nca logs, nca attach, nca status
• Can be cancelled with nca cancel

IPC (Inter-Process Communication)

Running sessions expose a Unix domain socket for real-time event streaming and control:

$XDG_RUNTIME_DIR/nca/<session-id>.sock
# or
/tmp/nca/<session-id>.sock

The IPC protocol uses newline-delimited JSON:

Events (session → client): EventEnvelope objects containing AgentEvent variants.

Commands (client → session):

• SendMessage — send a user message
• ApproveToolCall — approve a pending tool call
• DenyToolCall — deny a pending tool call
• AnswerQuestion — answer an agent question
• Cancel — cancel the current operation
• Shutdown — shut down the session

This enables building external UIs, monitoring dashboards, and automation scripts that interact with running sessions.

Parent-Child Sessions

When the agent spawns sub-agents, a parent-child relationship is tracked:

• Parent session records child session IDs
• Child session records parent session ID and inherited summary
• The spawn reason is stored in child metadata
• Child sessions can optionally run in isolated git worktrees

View child sessions:

/agents                    # List child sessions in interactive mode

nca sessions --search "child"   # Search for sub-agent sessions