augur

augur is a tiny Claude-style assistant client written in Zig. It talks to OpenRouter, supports tool calling, and ships with a simple REPL. This project started as the CodeCrafters course "Build your own Claude Code."

Requirements

• Zig 0.15+
• An OpenRouter API key (OPENROUTER_API_KEY)

Build

zig build

Install

bash -lc 'set -euo pipefail; INSTALL_DIR="${AUGUR_INSTALL_DIR:-$HOME/.local/bin}"; mkdir -p "$INSTALL_DIR"; zig build >/dev/null 2>&1 || { echo "Build failed"; exit 1; }; BIN_PATH="zig-out/bin/augur"; if [ ! -f "$BIN_PATH" ]; then echo "Binary not found at $BIN_PATH"; exit 1; fi; cp -f "$BIN_PATH" "$INSTALL_DIR/augur" && echo "augur installed to $INSTALL_DIR/augur"; case ":$PATH:" in *":$INSTALL_DIR:"*) ;; *) echo "Add to PATH: export PATH=\"$INSTALL_DIR:\$PATH\"";; esac'

Run prompt(s)

# streams by default
OPENROUTER_API_KEY=... zig build run -- -p "Say hello"

# queue multiple prompts in order
OPENROUTER_API_KEY=... zig build run -- -p "step 1" -p "step 2"

Start the REPL

OPENROUTER_API_KEY=... zig build run

Type /quit to leave the REPL.

The REPL uses ANSI colors when stdout is a TTY and starts in plan mode. Conversations are persisted to ./augur/conversations.json and switching conversations restores their message history into the active context buffer.

Slash commands

Inside the REPL:

• /plan switches to plan mode (high-level steps, no code).
• /build switches to build mode (implementation + code).
• /pair switches to pair mode (direction-first pair programming + code).
• /model shows the current OpenRouter model.
• /model <id> changes the OpenRouter model.
• /new [name] creates and switches to a new conversation.
• /switch <name> switches to a saved conversation (loads its history into context).
• /convos lists all conversations.
• /init inspects the project and generates an AGENTS.md.
• /quit exits the REPL.
• /help shows the command list.

Instruction files

Augur now detects repository skill guidance and appends it to the system prompt:

• SKILLS.md
• SKILLS/*/SKILL.md
• .skills/*/SKILL.md

When skills are present, the assistant is instructed to read relevant SKILL.md files before implementation.

Environment variables

• OPENROUTER_API_KEY (required)
• OPENROUTER_BASE_URL (optional, defaults to https://openrouter.ai/api/v1)

Tools

The assistant can call these tools:

• read: Read a file from disk.
• write: Write a file to disk.
• bash: Run a shell command and return stdout/stderr.

Roadmap

• Streamed responses (default)
• Model choice
• Plan, Build, and Pair modes
• Conversation persistence + switching
• SKILLS discovery (SKILLS.md, SKILLS/*/SKILL.md, .skills/*/SKILL.md)
• Streaming wait indicator before first token
• Per-response token usage + context-window %
• Context-bound tool loop (continues while context remains)
• Scoped AGENTS.md loading by directory tree
• Web search tool
• Subagents