---
title: "Session \u0026 Task Management"
description: "Manage nctl ai sessions, track tasks, control execution limits, and use plan mode for structured review before execution."
diataxis: reference
applies_to:
  product: "nctl"
audience: ["developer","platform-engineer"]
last_updated: 2026-04-16
url: https://docs.nirmata.io/docs/ai/nctl-ai/session-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:**

| Command | Description |
|---------|-------------|
| `sessions` | List all available sessions |
| `save` | Save current session |
| `new` | Create a new session |
| `resume <id>` | Resume a specific session (or `latest`) |
| `exit` / `quit` / `q` | Save session and exit |
| `exit-nosave` | Exit without saving |

**CLI flags:**

```bash
# 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:**

| Command | Description |
|---------|-------------|
| `tasks` | Show current todo list and task progress |
| `task <N>` | Show detailed information for task N (including worker output) |

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:

| Flag | Default | Description |
|------|---------|-------------|
| `--max-tool-calls` | 200 | Maximum total tool calls before the agent stops |
| `--max-background-workers` | 3 | Maximum parallel background workers spawned per tool call |

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

```bash
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.

```bash
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:

```text
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

| Command | Description |
|---------|-------------|
| `plan` | Show the current plan and its status |

### 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.