CLAUDE.md

Project Overview

Purpose: This project is a privacy-first, locally-running Python coding agent — similar in spirit to ollama-code / Claude Code — that uses a local LLM (via Ollama or compatible OpenAI-spec endpoint) to perform autonomous coding tasks inside a project directory.

Technologies: Python 3.11+, Ollama (local LLM backend), Rich (terminal UI), Pydantic, YAML config

Description: A single-purpose interactive agent script that accepts natural language tasks and autonomously executes them using a defined toolset for filesystem operations, shell execution, code search, and file manipulation. The agent runs a tool-call loop: it sends the user task and conversation history to the LLM, receives tool calls, executes them safely, and feeds results back until the task is complete or the agent yields control. It is intentionally scoped — not a full Claude Code replacement, but a capable local alternative for day-to-day coding workflows.

Inspiration: ollama-code (itself a fork of qwen-code / Gemini CLI), adapted to a clean Python architecture.

Development Guidelines

Project Structure

project-root/
├── app/
│   ├── agent/              # Core agent loop and orchestration
│   │   ├── loop.py         # Main ReAct-style tool-call loop
│   │   └── context.py      # Conversation history and session state
│   ├── tools/              # All agent-callable tools (one file per tool or group)
│   │   ├── base.py         # BaseTool ABC and ToolResult dataclass
│   │   ├── filesystem.py   # read_file, write_file, list_dir, make_dir, delete_file
│   │   ├── shell.py        # run_command (with sandboxing/allow-list)
│   │   ├── search.py       # grep_files, find_files
│   │   ├── edit.py         # str_replace, patch_apply
│   │   └── registry.py     # Tool registration and schema export
│   ├── services/
│   │   ├── llm.py          # LLM client wrapper (Ollama / OpenAI-spec)
│   │   ├── streaming.py    # Streaming response handler
│   │   └── permissions.py  # Approval gating for destructive operations
│   ├── models/
│   │   ├── config.py       # Pydantic config model
│   │   ├── tool_call.py    # ToolCall / ToolResult schemas
│   │   └── message.py      # Message schema (role, content, tool_calls)
│   ├── utils/
│   │   ├── logging.py      # Centralized logger (Rich handler)
│   │   ├── display.py      # Rich console output helpers
│   │   ├── file_helpers.py # Safe path resolution, binary detection, size guards
│   │   └── token_counter.py# Approximate token usage tracking
│   └── main.py             # Entrypoint — arg parsing, config load, agent kickoff
├── config/
│   └── config.yaml         # YAML-driven config (model, endpoint, tool permissions, limits)
├── docs/
│   ├── code_guidelines.md
│   ├── security.md
│   └── tools.md            # Tool spec and usage reference
├── tests/
│   ├── unit/
│   └── integration/
├── CLAUDE.md
├── pyproject.toml
└── README.md

I prefer source in app/, not src/. Common logic (logging, HTTP, validators) is centralized. Structure is modular with services, utils, models, and tools as distinct layers. Typed config loaders and YAML-driven config structures are preferred.

Coding Standards

I follow a brainstorm → design → code → revise flow and like maintaining that pattern across sessions.

Reference docs/code_guidelines.md for full code standards and rules. Key highlights:

All functions and classes must have type annotations
Pydantic v2 for all data models and config validation
Tool implementations must inherit from BaseTool and return ToolResult
Tool schemas must be auto-generated from docstrings + type hints for LLM consumption
Async-first where appropriate (especially LLM streaming)
No raw string path manipulation — use pathlib.Path throughout
All file operations must go through file_helpers.py safe wrappers (path traversal guards, binary detection, size limits)
Shell commands must go through the permissions service before execution

Security Standards

Reference docs/security.md for full security guidance. Key highlights for this project:

No shell passthrough without approval gating — destructive or side-effectful commands require explicit user confirmation
Path traversal protection — all file operations must be validated against a configurable workspace_root
No secrets in config.yaml — API keys (if ever needed) go in .env, never committed
Tool allow/deny lists — configurable per-tool enable/disable in config.yaml
LLM response validation — tool call arguments must be validated against schema before execution; never eval() LLM output

⚠️ CLAUDE WORKSPACE BELOW ⚠️

The sections above define my development preferences and standards. Everything below this line is working context for Claude to track project-specific information, decisions, and progress.

Claude Context & Project Notes

Project Context

Agent pattern: ReAct-style loop (Reason + Act). LLM emits tool calls; agent executes and feeds results back in the next turn. Loop terminates on a plain-text response with no tool calls (task complete) or explicit finish tool call.
LLM backend: Ollama with OpenAI-compatible /v1/chat/completions endpoint. llm.py should abstract the client so swapping to another local backend is a config change, not a code change.
Tool call format: Follow OpenAI function-calling spec (tools parameter with JSON schema). Models that support this natively (e.g., qwen2.5-coder, llama3.1, mistral-nemo) are preferred targets.
Core tools to implement first: read_file, write_file, list_dir, str_replace, run_command, grep_files, find_files
Streaming: Stream LLM output to terminal using Rich live display; tool calls are parsed from the accumulated stream before execution.
Permissions model: Two-tier — auto-approve reads and searches; prompt user for writes, deletes, and shell commands (configurable strictness in config.yaml).

Implementation Notes

Define BaseTool ABC and ToolResult dataclass before implementing any individual tools
Implement registry.py early — tool schema export is needed to construct the LLM system prompt
Token counting is approximate (character-based heuristic is fine for v1, tiktoken optional)
str_replace tool should require unique match — fail loudly if the old_str appears more than once (mirrors Claude Code behavior)
Config loader should validate and error clearly on missing required fields (model name, endpoint)

Session History

Project initialized — CLAUDE.md created, architecture scoped.

Active Tasks & Notes

Define project scaffolding (pyproject.toml, folder structure, base files)
Draft docs/code_guidelines.md and docs/security.md
Implement BaseTool + ToolResult + registry.py first
Implement filesystem.py tools with safe path wrappers
Wire up llm.py against local Ollama endpoint

Change Log

Date	Change
2026-03-11	Project scoped and CLAUDE.md initialized

7.7 KiB Raw Permalink Blame History