Add agent commands for AI-assisted task planning and execution #10

mattzcarey · 2026-01-09T14:44:20Z

Summary

This PR adds the zagi agent command suite for AI-assisted task planning and execution using the RALPH pattern (Recursive Agent Loop Pattern for Humans).

New Commands

zagi agent plan - Interactive planning sessions with AI
zagi agent run - Automated task execution loop
zagi tasks import - Import tasks from markdown plan files

Usage

Planning with `agent plan`

Start an interactive planning session where an AI agent helps you design and create tasks:

# Start interactive session (agent asks what you want to build)
zagi agent plan

# Start with initial context
zagi agent plan "Add user authentication with JWT"

# Preview the prompt without executing
zagi agent plan --dry-run

The planning agent follows a collaborative protocol:

Explores codebase - Reads AGENTS.md and relevant code
Asks clarifying questions - Scope, constraints, preferences
Proposes plan - Presents numbered implementation steps
Creates tasks - Only after you explicitly approve

Running tasks with `agent run`

Execute the RALPH loop to automatically complete pending tasks:

# Run until all tasks complete (or fail 3x)
zagi agent run

# Run only one task then exit
zagi agent run --once

# Safety limit - stop after N tasks
zagi agent run --max-tasks 10

# Preview what would run
zagi agent run --dry-run

Importing tasks from plans

Convert a markdown plan file into tasks:

# Import tasks from a plan file
zagi tasks import plan.md

Executor Configuration

Control which AI executes tasks:

# Use Claude Code (default)
ZAGI_AGENT=claude zagi agent run

# Use opencode
ZAGI_AGENT=opencode zagi agent run

# Use a custom command
ZAGI_AGENT_CMD="aider --yes" zagi agent run

Agent Safety Features

When ZAGI_AGENT is set:

Append-only editing: tasks edit appends instead of replacing (prevents accidental overwrites)
Blocked destructive commands: reset --hard, push --force, clean -f, etc.
Required commit prompts: git commit requires --prompt flag

Test Plan

Unit tests for agent.zig
Integration tests for agent plan --dry-run
Integration tests for agent run with mocked executor
Tests for append-only task editing
Tests for error conditions and edge cases
Tests for ZAGI_AGENT_CMD override

Generated with Claude Code

Implements the RALPH (Run Agent Loop with Prompts Headlessly) workflow: - --claude (default), --opencode, --runner flags for different runners - --model flag to specify model - --once flag to run single task - --dry-run flag to preview without executing - --delay and --max-tasks safety controls - Failure tracking: skips tasks after 3 consecutive failures - Added --json support to ready command for programmatic access Also updates start.sh to be a generic RALPH runner script with: - Auto-detection of zagi binary - --import flag to import tasks from plan.md - Same flags as git tasks run 🤖 Generated with [Claude Code](https://claude.com/claude-code)

- Add new `zagi agent` command for RALPH loop execution - Remove `tasks run` subcommand (replaced by `zagi agent`) - Remove `--after` dependency syntax from tasks (simplify model) - Remove `ready` command (no longer needed without dependencies) - Support --executor flag for claudecode/opencode/custom commands - Support ZAGI_AGENT env var as default executor - Add logging to agent.log file - Add --once, --dry-run, --delay, --max-tasks safety options 🤖 Generated with [Claude Code](https://claude.com/claude-code)

- Rename 'claudecode' to 'claude' for consistency - Remove --executor flag, use ZAGI_AGENT env var only - Add ZAGI_AGENT_CMD for custom command override - Fix segfault: dupe task.id key before storing in hashmap - Remove default model - use executor defaults (claude -p, opencode run)

- Implement `zagi agent plan` for starting planning sessions - Add planning prompt with detailed instructions for task creation - Support ZAGI_AGENT_CMD for custom executor commands - Update tests to remove obsolete --after and ready references - Create friction.md documenting known issues: - ZAGI_AGENT validation missing - Relative path issues in agent - Memory leaks in tasks.zig - Add tasks 011-014 for friction fixes 🤖 Generated with [Claude Code](https://claude.com/claude-code)

- Move deinit() call after print in runDelete to avoid printing freed memory - Update non-git directory test to accept both "error" and "fatal" messages 🤖 Generated with [Claude Code](https://claude.com/claude-code)

- Add escapeJsonString() helper for proper JSON output - Escape quotes, backslashes, newlines in task content for --json - Update start.sh to use tasks list --json (removed 'ready' command) - Use python3 for reliable JSON parsing of first pending task 🤖 Generated with [Claude Code](https://claude.com/claude-code)

- Use --output-format stream-json for real-time observability - Add --dangerously-skip-permissions by default for headless runs - Support CC_CMD env var to override claude command - Log per-task JSON to logs/<task-id>.json 🤖 Generated with [Claude Code](https://claude.com/claude-code)

…ipts) Shell aliases like 'cc' aren't available in scripts, so use the full 'claude --dangerously-skip-permissions' command directly. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Validates ZAGI_AGENT against known executors ('claude', 'opencode'). Invalid values like '1' now show clear error with valid options. ZAGI_AGENT_CMD bypasses validation for custom executors.

Agents now read CONTEXT.md first to understand the overall mission, current focus, and work streams before tackling their specific task. Includes link to RALPH methodology. CONTEXT.md is ephemeral - lives for PR lifetime, deleted before merge.

Document the key concepts in the agent module: - planning_prompt_template: explains its purpose for creating self-contained, verifiable tasks during interactive planning - RALPH loop algorithm: ASCII diagram showing the execution flow with failure handling, safety limits, and exit conditions - consecutive_failures tracking: explains why we track consecutive (not total) failures and the memory management for duplicated keys

Test suite covers: - RALPH loop behavior (task execution, --once, --max-tasks) - Consecutive failure counting (increment on failure, reset on success) - Max failures exit condition (skip after 3 failures, exit when all fail) - Dry-run mode output verification - Task completion integration (marks tasks done) - Error handling (invalid ZAGI_AGENT, ZAGI_AGENT_CMD bypass)

- Reduce createFixtureRepo commit count from 100 to 20 - Switch 6 test files to use lightweight createTestRepo (1 commit) - Tests now create their own specific fixtures as needed - Result: ~74-93% faster test execution (411s -> 30s wall-clock)

Add --parallel flag to agent run command for concurrent task execution. When parallel > 1, tasks run simultaneously with streaming JSON output to individual log files (logs/<task-id>.json). Features: - --parallel <n> flag to run n tasks concurrently - Streaming JSON output via --output-format stream-json for Claude - Per-task log files for real-time visibility - Proper tracking of running tasks and completion handling - Maintains sequential mode (parallel=1) as default The parallel execution uses shell redirection to stream output directly to log files, enabling real-time monitoring of agent progress. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Add two new unit tests to verify appendToTask correctly handles content containing newlines: - Test appending multi-line content to single-line original - Test when both original and addition have embedded newlines The function preserves newlines in the output; escaping for storage happens at the serialization layer via escapeContentForStorage. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

- Change 'Goal:' to 'Initial context:' (matches actual output) - Change 'PROJECT GOAL:' to 'INITIAL CONTEXT:' (matches prompt template) - Update prompt section checks (PHASE 1/4, RULES) - Fix executor expectations (claude not claude -p for interactive) - Update edit test for append-only agent behavior - Clear ZAGI_AGENT_CMD in test helper to isolate tests - Use 'claude' instead of deprecated 'claude-code'

The planning session runs interactively with the default executor model. Model selection is only available for agent run. Co-Authored-By: Claude Opus 4.5 <[email protected]>

Model selection is handled by the executor itself. This simplifies the agent interface - users configure their preferred model in the executor's own config (e.g., claude settings). Co-Authored-By: Claude Opus 4.5 <[email protected]>

- Log files now go to /tmp/zagi/<repo>/<hash>.log instead of agent.log - Simplified completion promise to just "TASK_DONE" - Task only completes if agent outputs TASK_DONE marker - Capture and display agent output after completion Co-Authored-By: Claude Opus 4.5 <[email protected]>

- Require both start and end markers of completion promise - Add knowledge persistence section for AGENTS.md updates - Simplified completion promise bullet points Co-Authored-By: Claude Opus 4.5 <[email protected]>

…ands - When ZAGI_AGENT_CMD is set with ZAGI_AGENT, mode flags are auto-added (-p for claude, run for opencode) - Add docs/setup.md with full executor configuration documentation - Add Zig tests for buildExecutorArgs covering all scenarios - Update AGENTS.md to reference new setup docs

- Split --prompts to only show prompts (200 char truncation) - Add --agent flag to show agent name only - Add --session flag to show session transcript - Add --session-offset=N and --session-limit=N for pagination - Shows byte range and suggests next offset when truncated

- Document new log flags: --prompts, --agent, --session - Document session pagination: --session-offset, --session-limit - Document git notes namespaces for AI metadata - Update agent mode docs to reflect auto-detection from environment - Clarify ZAGI_AGENT is for executor selection, agent mode is auto-detected

mattzcarey added 30 commits January 9, 2026 14:56

Update plan.md progress checkboxes

603d734

Fix use-after-free in runDelete and test assertion

cb8632b

- Move deinit() call after print in runDelete to avoid printing freed memory - Update non-git directory test to accept both "error" and "fatal" messages 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Add friction.md documenting API issues encountered

46e7565

Fix start.sh to use full claude command (cc alias doesn't work in scr…

e3622d9

…ipts) Shell aliases like 'cc' aren't available in scripts, so use the full 'claude --dangerously-skip-permissions' command directly. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Add ZAGI_AGENT validation for invalid values

8c19e01

Validates ZAGI_AGENT against known executors ('claude', 'opencode'). Invalid values like '1' now show clear error with valid options. ZAGI_AGENT_CMD bypasses validation for custom executors.

Fix relative path in getPendingTasks() using selfExePath()

68cdf5a

Add CONTEXT.md for agent mission context

a30c151

Agents now read CONTEXT.md first to understand the overall mission, current focus, and work streams before tackling their specific task. Includes link to RALPH methodology. CONTEXT.md is ephemeral - lives for PR lifetime, deleted before merge.

Fix hardcoded binary path in agent prompts - resolve dynamically

9f89a18

Fix memory leaks in agent.zig consecutive_failures hashmap

9ad1dbc

Cleanup agent.zig - consolidate duplicate logic and simplify

3b4287b

Document agent subcommands in AGENTS.md

0a84822

Document environment variables in README.md

d89e65e

Style agent.zig help text to match project conventions

5617544

Add comprehensive tests for agent plan --dry-run

9403eb3

Add tests for ZAGI_AGENT_CMD override

5732555

Add tests for error conditions

077179c

Update agent run prompts with executor-aware documentation persistence

be3d818

Implement append-only task editing for agents

f9ecfe0

Add agent CLI tests for args and executor paths

8280280

Add --output-format stream-json flag to agent run

0d14152

mattzcarey added 9 commits January 9, 2026 14:57

Add COMPLETION PROMISE requirement to agent task prompts

5c7bf61

Merge git-tasks into git-agent-run - resolve test file conflicts

05ce496

Redesign zagi agent plan as interactive session

62c0376

Update planning prompt to explore codebase before asking questions

7be7c3e

Add clarifying questions phase to interactive planning

ad75956

Add tasks import command for plan-to-tasks conversion

45eafef

Make zagi agent plan interactive with stdin/stdout passthrough

7a14484

mattzcarey force-pushed the git-agent-plan branch from 64055a5 to 7a14484 Compare January 9, 2026 14:58

mattzcarey changed the title ~~Git agent plan~~ Add agent commands for AI-assisted task planning and execution Jan 9, 2026

mattzcarey and others added 8 commits January 9, 2026 15:02

Remove --model flag from agent plan

0d6c833

The planning session runs interactively with the default executor model. Model selection is only available for agent run. Co-Authored-By: Claude Opus 4.5 <[email protected]>

Remove --model flag from agent commands

bea8d54

Model selection is handled by the executor itself. This simplifies the agent interface - users configure their preferred model in the executor's own config (e.g., claude settings). Co-Authored-By: Claude Opus 4.5 <[email protected]>

Add knowledge persistence and fix completion promise

5843949

- Require both start and end markers of completion promise - Add knowledge persistence section for AGENTS.md updates - Simplified completion promise bullet points Co-Authored-By: Claude Opus 4.5 <[email protected]>

Add AI agent attribution with separate git notes namespaces

66ffbe7

mattzcarey merged commit 6dd4162 into main Jan 9, 2026
1 check passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add agent commands for AI-assisted task planning and execution #10

Add agent commands for AI-assisted task planning and execution #10

Uh oh!

mattzcarey commented Jan 9, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Add agent commands for AI-assisted task planning and execution #10

Add agent commands for AI-assisted task planning and execution #10

Uh oh!

Conversation

mattzcarey commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

New Commands

Usage

Planning with agent plan

Running tasks with agent run

Importing tasks from plans

Executor Configuration

Agent Safety Features

Test Plan

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mattzcarey commented Jan 9, 2026 •

edited

Loading

Planning with `agent plan`

Running tasks with `agent run`