Agent Mode: Task Execution

​

How to Start

/agent find all log files modified in the last 24h and copy them to 'recent_logs'

​

The Agent Cycle

​

How the Agent Works Internally

​

The ReAct Loop

1. Build history — The conversation history is assembled with an anchor reminder (format reminder) appended at the end. This anchor reinforces the expected response format for the AI, preventing it from “forgetting” instructions during long conversations.
2. Call the LLM — The complete history is sent to the configured AI provider.
3. Parse the response — The response is analyzed to extract reasoning, explanations, tool calls, and commands.
4. Execute actions — Tools and commands are executed with appropriate security controls.
5. Inject feedback — Execution results are injected back into the history as context messages.
6. Next turn — The loop returns to step 1, until the AI completes the task or the turn limit is reached.

​

System Prompt Composition

• Workspace context — Bootstrap files like SOUL.md, USER.md, and persistent memory
• Tool descriptions — Complete list of available plugins and their parameters
• Active persona — If a custom persona is configured, it is included
• Format instructions — The AgentFormatInstructions that define the expected response format

​

AI Response Format

​

Cancellation and Ctrl+C

• During LLM call — Ctrl+C cancels the request via context.WithCancel(). Any partial response received up to that point is discarded.
• Per-turn check — At the start of each ReAct loop turn, the agent checks context.Done(). If the context has been cancelled, the loop terminates immediately.
• Signal handling — SIGINT and SIGTERM are caught by the runWithCancellation() function, which coordinates graceful shutdown.
• Type-ahead queue — Messages typed by the user during AI processing are queued and processed once the current turn finishes. This prevents input loss. Works in both /agent AND /coder. The spinner shows (N queued) in real time as you press Enter — no need to wait for the turn to close to see the counter rise.

​

History and Compaction

​

Compaction Strategy

1. Trimming — Injected context messages (tool results, command outputs) longer than 3000 characters are truncated, preserving the beginning and end.
2. Summarization — Intermediate messages are summarized by the AI itself, keeping key points.
3. Emergency truncation — If the previous levels are not sufficient, the oldest messages are removed.

​

Checkpoint and /rewind

​

Action Plan Interface

PLAN (compact view)
  #1: Create the destination directory -- mkdir -p recent_logs
  #2: Find and copy the files -- find ~ -name "*.log" -mtime -1 -exec cp {} recent_logs/ \;

COMMAND #2: Find and copy the files
    Type:   shell
    Risk:   Safe
    Status: Pending
    Code:
      $ find ~ -name "*.log" -mtime -1 -exec cp {} recent_logs/ \;

​

Interactive Menu

​

Security

​

Agent Mode Security

​

Command Allowlist (CHATCLI_AGENT_SECURITY_MODE)

export CHATCLI_AGENT_SECURITY_MODE=strict

export CHATCLI_AGENT_SECURITY_MODE=permissive

# Add terraform and ansible to the allowlist
export CHATCLI_AGENT_ALLOWLIST="terraform;ansible;packer"

# The agent tries to run "terraform plan" but it is blocked in strict mode
# Error: "command 'terraform' is not in the allowed commands list"

# Solution: add terraform to the allowlist
export CHATCLI_AGENT_ALLOWLIST="terraform"
# Now "terraform plan", "terraform apply", etc. work

​

Sensitive Read Path Protection (CHATCLI_AGENT_WORKSPACE_STRICT)

# Enable workspace boundary enforcement
export CHATCLI_AGENT_WORKSPACE_STRICT=true

# Allow kubeconfig access (for K8s operations)
export CHATCLI_AGENT_ALLOW_KUBECONFIG=true

# Allow additional read paths
export CHATCLI_AGENT_EXTRA_READ_PATHS="/opt/configs;/var/log/myapp"

​

Shell Config (CHATCLI_AGENT_SOURCE_SHELL_CONFIG)

# Enable shell config sourcing (opt-in)
export CHATCLI_AGENT_SOURCE_SHELL_CONFIG=true

• File ownership — The file must be owned by the current user
• File size — A safety limit to prevent sourcing excessively large files

​

Command Output Sanitization

• Prompt injection detection — Suspicious patterns in output (e.g., instructions for the AI to ignore rules) are detected and sanitized before being injected into context
• Size limits — Command outputs are truncated to prevent excessive token consumption

# Configure command output limit (default: 50000 characters)
export CHATCLI_MAX_COMMAND_OUTPUT=100000

​

Unified History and Context

• Start a conversation in chat, enter /agent, and the AI will have all the previous context
• Use /compact to reduce history when it gets large
• Use /rewind (or Esc+Esc) to go back to an earlier point in the conversation

​

Agent Mode Configuration

export CHATCLI_AGENT_PLUGIN_MAX_TURNS=100
export CHATCLI_AGENT_CMD_TIMEOUT=30m

​

One-Shot Mode (-p flag)

chatcli -p "list all stopped Docker containers"

​

How it works

1. The instruction is sent to the LLM as a single turn (no ReAct loop).
2. A thinking animation is displayed while the AI processes.
3. If the --auto-execute flag is active, the first command block in the response is executed automatically — but only after passing the dangerous command check.
4. The result is displayed and the process exits.

​

Workspace and large payloads

​

Next Steps