Session & Task Management

Applies to: nctl 4.0 and later

Session Management

Sessions automatically capture your conversation history, tool calls, and results. You can resume any previous session to continue where you left off.

Interactive commands:

CLI flags:

# Start a new session
nctl ai --new-session

# Resume the most recent session
nctl ai --resume-session latest

# Resume a specific session by ID
nctl ai --resume-session 20260210-0206

# List all available sessions
nctl ai --list-sessions

# Delete a session by ID
nctl ai --delete-session 20260210-0206

Sessions work with any provider (Nirmata, Anthropic, Bedrock, etc.) and are saved periodically during conversation. Use Ctrl+D to explicitly save and exit, or Ctrl+C to exit without saving (the session ID is displayed for later resuming).

Task Management

nctl ai tracks tasks automatically during complex, multi-step operations. The agent creates and updates a task list as it works, giving you visibility into progress.

Interactive commands:

The task list updates in real time as the agent works through multi-step workflows like cluster scanning, policy generation, or compliance assessments.

Execution Limits

Two flags control how much work the agent is allowed to do in a single run:

These are useful in non-interactive pipelines to cap cost and execution time:

nctl ai --max-tool-calls 50 --max-background-workers 1 --prompt "scan my cluster"

Plan Mode

Plan mode adds a structured review step before the agent executes any actions. When enabled with --plan, the agent must first create a written plan and present it to you for approval before running any tools that modify state.

nctl ai --plan --prompt "generate pod security policies for my cluster"

How It Works

1. Plan creation — The agent analyzes your request and creates a structured PLAN.md listing all tasks it intends to execute.
2. Review — The plan is displayed in your terminal. You are prompted to approve, reject, or provide feedback.
3. Approval — On approval, the plan is converted to a task list and execution begins.
4. Feedback loop — If you describe changes instead of approving, the agent updates the plan and prompts again.
5. Rejection — Replying with no (or similar) discards the plan without executing anything.

Approval Prompt

After the plan is displayed, you will see:

Does this plan look good? Reply with yes/no to approve or reject, or describe any changes you'd like.

• yes, y, approve, ok, looks good — approve and begin execution
• no, n, reject, cancel — discard the plan
• Any other text — treated as feedback; the agent revises the plan and prompts again

What Runs Without Approval

Read-only and scanning tools are always available so the agent can gather context while building the plan:

• File reads and directory listings
• scan_kubernetes, scan_resources, scan_terraform
• File search tools

All tools that write files, execute commands, or modify resources are blocked until the plan is approved.

Interactive Plan Commands

When to Use Plan Mode

Plan mode is useful for complex or multi-step requests where you want to review and confirm the agent’s intended actions before any changes are made — for example, generating a set of policies across multiple directories, or remediating violations across a cluster.

For simple, single-step requests, the agent handles planning automatically. Use --plan to force the review step even for simpler tasks.