CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

agent0 is an agentic coding TUI built with Babashka (Clojure). It runs local LLMs via Ollama with tool-use capabilities (file editing, shell commands, code search, web research) in a terminal interface.

Running

agent                          # Interactive
agent "prompt"                 # With initial prompt
agent --continue               # Resume latest session
agent --session <uuid>         # Resume specific session

Requirements: Babashka, Ollama running locally. Model defaults to qwen3-coder-next (override with $AGENT_MODEL). Ollama host defaults to http://localhost:11434 (override with $OLLAMA_HOST).

Architecture

Runtime: Babashka scripts (bb.edn), depends on local ../clojure-tui for the TUI framework.

Source files (src/agent/):

app.clj — TUI layer. Elm-architecture: view renders state, update-fn handles events. The agent loop runs async in a background thread; UI polls an event queue every 100ms. Manages session persistence, skill expansion, scrolling, and input.
core.clj — Agent brain. run-agent-loop! iterates: call LLM → execute tool calls → append results → repeat (max 50 iterations). Tools return strings or {:message str :diff str} maps. Includes stuck-loop detection (exact repeats and research loops). build-system-prompt composes the base prompt with project context.
context.clj — Loads project context from .agent0/context.md, CLAUDE.md, .cursorrules, or .github/copilot-instructions.md. Parses skill definitions from ~/.config/agent0/skills.md (global) and .agent0/skills.md (project). Skills are /name <arg> templates with {param} substitution.
markdown.clj — Converts markdown to ANSI-styled terminal text. Handles inline formatting, code blocks, headers, lists, links, and ANSI-aware word wrapping.
web_search.clj — Subagent config for web research. Uses DuckDuckGo HTML search + URL fetching. Delegated to via the delegate tool.

Data flow: User input → skill expansion (if /command) → conversation history → run-agent-loop! (background future) → LLM call → tool execution → events pushed to atom queue → UI polls and renders.

Event types: :text (assistant response), :tool (tool label), :diff (file change preview), :error, :done.

Persistence: Sessions in ~/.local/share/agent0/sessions/, logs in ~/.local/share/agent0/logs/.

Key Patterns

Tools that modify files (edit-file, create-file) return {:message ... :diff ...} maps. execute-tool extracts the diff and passes it as a separate UI event. The LLM only sees the :message string.
The TUI uses clojure-tui's hiccup-like syntax: [:row {:widths [22 :flex]} left right], [:col {:heights [:flex 3]} content input], [:box {:border :rounded}], [:text {:fg :red :bold true} "text"].
run-agent-loop! returns {:future f :cancel! atom}. Setting cancel! to true + future-cancel interrupts the loop.
Subagents (web_search) are synchronous mini-loops with their own tools and system prompt, invoked via the delegate tool.

No Tests

There is no test suite. Verify changes by loading namespaces in the nREPL (bb nrepl-server) and testing functions interactively.

3.3 KiB Raw Blame History