<!-- source: https://deepwiki.com/qhkm/zeptoclaw/4.2-agent-commands -->

# Agent Commands

- docs/superpowers/plans/2026-03-13-deep-research-and-clarification.md
- docs/superpowers/specs/2026-03-13-deep-research-skill-and-clarification-tool-design.md
- skills/deep-research/SKILL.md
- src/cli/agent.rs
- src/cli/batch.rs
- src/cli/shimmer.rs
- src/cli/slash.rs

This page documents the CLI commands for direct agent interaction: `agent`, `agent-stdin`, and `batch`. These commands provide synchronous, request-response communication with the agent, as opposed to the asynchronous gateway mode covered in [Gateway Commands](/qhkm/zeptoclaw/4.3-gateway-commands).

ZeptoClaw's CLI architecture is built using `clap` for command parsing and dispatch, routing logic from `main.rs` through `cli/mod.rs` to specific command handlers. [src/cli/mod.rs40-47](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L40-L47)

## Command Overview

ZeptoClaw provides three primary agent execution modes:

Sources: [src/cli/mod.rs61-98](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L61-L98) [src/cli/mod.rs109](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L109-L109)

## Agent Command Structure

The `agent` command handles both single-message execution and the interactive REPL. When run without the `--message` flag, it initializes a `rustyline` editor for an interactive session using `SlashHelper` for command completion. [src/cli/agent.rs116-122](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/agent.rs#L116-L122) [src/cli/agent.rs256-270](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/agent.rs#L256-L270) [src/cli/slash.rs89-91](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/slash.rs#L89-L91)

### CLI to Code Entity Mapping

```

```

**Figure 1: Command to Entity Mapping**

Sources: [src/cli/agent.rs116-153](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/agent.rs#L116-L153) [src/cli/batch.rs18-44](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/batch.rs#L18-L44) [src/cli/slash.rs89-98](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/slash.rs#L89-L98) [src/cli/shimmer.rs30-37](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/shimmer.rs#L30-L37)

## Interactive and Streaming Features

### Shimmer and Feedback

The `agent` command implements a "Thinking..." animation using the `ShimmerSpinner` class. It renders a gradient text wave animation on `stderr` while the LLM is processing. [src/cli/shimmer.rs1-6](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/shimmer.rs#L1-L6) The CLI spawns a feedback printer that listens to `ToolFeedbackPhase` events (e.g., `Thinking`, `Starting`, `Done`) sent from the `AgentLoop` via an unbounded channel to update the CLI state with step numbers and elapsed time. [src/cli/agent.rs166-210](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/agent.rs#L166-L210) [src/cli/shimmer.rs120-174](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/shimmer.rs#L120-L174)

### Slash Commands

Interactive mode supports "slash commands" handled by the `SlashHelper`. These allow runtime configuration of the agent session without restarting. [src/cli/slash.rs19-86](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/slash.rs#L19-L86)

Sources: [src/cli/slash.rs19-86](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/slash.rs#L19-L86)

### Streaming Implementation

Streaming is enabled by default but can be disabled with `--no-stream`. When active, `cmd_agent` calls `agent.process_message_streaming()`, which returns a `mpsc::Receiver<StreamEvent>`. [src/cli/mod.rs69-70](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/mod.rs#L69-L70) [src/cli/agent.rs317-325](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/agent.rs#L317-L325)

```

```

**Figure 2: Streaming Data Flow**

Sources: [src/cli/agent.rs317-340](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/agent.rs#L317-L340) [src/cli/shimmer.rs30-105](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/shimmer.rs#L30-L105) [src/cli/slash.rs19-86](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/slash.rs#L19-L86)

## Batch Command

The `batch` command allows processing multiple prompts sequentially. It marks messages with `is_batch: true` in the `InboundMessage` metadata to allow tools or logic to distinguish batch runs. [src/cli/batch.rs51-52](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/batch.rs#L51-L52)

### Batch Execution Logic

1. Load Prompts : Reads from .txt , .json , or .jsonl . src/cli/batch.rs 26-31
2. Template Application : Applies an optional template to the entire batch. src/cli/batch.rs 39-44
3. Sequential Processing : Loops through prompts, calling process_message or process_streaming (if --stream is set). src/cli/batch.rs 49-61
4. Format Results : Renders results into the requested BatchFormat (Text or JSONL). src/cli/batch.rs 88-92

Sources: [src/cli/batch.rs18-111](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/batch.rs#L18-L111)

## Tool Interruption and Clarification

The agent loop supports a `pause_for_input` mechanism, notably used by the `ask_clarification` tool. When a tool returns an output with `pause_for_input: true`, the CLI handler must stop processing the current tool chain and wait for user input. [docs/superpowers/plans/2026-03-13-deep-research-and-clarification.md5-7](https://github.com/qhkm/zeptoclaw/blob/2c743d31/docs/superpowers/plans/2026-03-13-deep-research-and-clarification.md?plain=1#L5-L7) [docs/superpowers/specs/2026-03-13-deep-research-skill-and-clarification-tool-design.md147-148](https://github.com/qhkm/zeptoclaw/blob/2c743d31/docs/superpowers/specs/2026-03-13-deep-research-skill-and-clarification-tool-design.md?plain=1#L147-L148)

### Trust and Local Sessions

The system distinguishes between "trusted local sessions" (interactive CLI) and remote sessions. Interactive CLI sessions are marked with `interactive_cli: true` and `trusted_local_session: true` metadata. [src/cli/agent.rs26-27](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/agent.rs#L26-L27)

```

```

**Figure 3: Session Trust and Interruption Flow**

Sources: [src/cli/agent.rs240-250](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/agent.rs#L240-L250) [docs/superpowers/specs/2026-03-13-deep-research-skill-and-clarification-tool-design.md189-192](https://github.com/qhkm/zeptoclaw/blob/2c743d31/docs/superpowers/specs/2026-03-13-deep-research-skill-and-clarification-tool-design.md?plain=1#L189-L192) [src/cli/batch.rs52](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/batch.rs#L52-L52)

## Tool Approval in CLI

For tools requiring approval (e.g., `shell` in assistant mode), the `agent` command provides a synchronous prompt. [src/cli/agent.rs67-105](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/agent.rs#L67-L105)

1. AgentLoop detects a tool requires approval via ApprovalGate .
2. It calls the ApprovalHandler provided by the CLI.
3. The CLI handler prompt_cli_approval prints the tool name/arguments and waits for [y/N] input. src/cli/agent.rs 71-78
4. The result is returned to the loop to either proceed or block. src/cli/agent.rs 89-91

Sources: [src/cli/agent.rs67-105](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/agent.rs#L67-L105)

## Implementation Details

### Key Functions

- cmd_agent : Main entry for interactive/single-message mode. src/cli/agent.rs 116
- cmd_batch : Main entry for file-based processing. src/cli/batch.rs 18
- prompt_cli_approval : Blocking CLI prompt for tool execution permission. src/cli/agent.rs 67
- process_streaming : Internal helper for batch streaming. src/cli/batch.rs 113

### Configuration Integration

The CLI commands default the workspace to the current working directory (`CWD`) if the config is set to the default `~/.zeptoclaw/workspace`. This ensures file tools resolve relative paths correctly in a terminal context. [src/cli/agent.rs128-132](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/agent.rs#L128-L132)

Sources: [src/cli/agent.rs123-132](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/agent.rs#L123-L132) [src/cli/batch.rs33-35](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/batch.rs#L33-L35)
