Coding Agent

An intelligent AI-powered coding agent that helps you write, edit, and run code. It provides conversational interactions with AI models while having direct access to your file system and shell commands.

Features

• Conversational AI - Chat with AI models using natural language
• File System Tools - Read, write, and edit files seamlessly
• Command Execution - Run shell commands safely with approval prompts
• Session Management - Resume previous conversations and track history
• Multi-Provider Support - Switch between local Ollama, Ollama Cloud, Cloudflare AI Gateway, and OpenRouter models
• Event Logging - Track all interactions and tool executions
• Reasoning Capture - Preserve provider-exposed reasoning traces when available
• Type-Safe - Built with TypeScript for reliability and type safety

Installation

Install from npm:

npm install -g @germanescobar/anita

That installs the anita command globally, so users can run:

anita chat "Create a simple React component that displays a greeting"

Local Development Install

To install from a local checkout:

# Clone the repository
git clone <repository-url>
cd coding-agent

# Install dependencies
npm install

# Build the project
npm run build

# Install the anita command globally from this checkout
npm link

After that, the anita command will be available in your shell.

npm link is typically a one-time setup step for a local checkout. After changing files in src/, run:

npm run build

You only need to run npm link again if the package's global command setup changes, such as the package name or the bin mapping in package.json.

If you don't want to install it globally, you can also run it directly from the repository with:

npm run start -- <command>

Usage

Basic Chat

Start a new conversation:

anita chat "Create a simple React component that displays a greeting"

Resume a Session

Continue from a previous conversation:

anita chat "Can you explain this code?" --resume <session-id>

List Past Sessions

anita sessions

View Event Logs

View detailed events for a specific session:

anita events <session-id>

List Supported Models

Show the built-in model choices grouped by provider:

anita models

Each listed value is a provider/model string that can be passed to --model. Local Ollama models use the ollama/ provider, while Ollama Cloud models use ollama-cloud/. Models that support attachments are annotated with [images], [files], or both.

Custom Model

Use a different AI model:

anita chat "Your message here" --model ollama/glm-4.7-flash:latest

Additional System Prompt

Add run-specific system instructions:

anita chat "Review this module" --system-prompt "Be concise and prioritize correctness issues."

--system-prompt is additive. It does not replace Anita's built-in instructions, safety rules, user instructions, or tool permission policy.

Attach an image or PDF to models that support the relevant attachment type:

anita chat "Explain this screenshot" --model openrouter/moonshotai/kimi-k2.6 --attach ./screen.png
anita chat "Summarize this brief" --model ollama-cloud/minimax-m3 --attach ./brief.pdf

--attach accepts local paths or HTTP(S) URLs and can be repeated. Supported local attachment types are png, jpg, jpeg, webp, gif, and pdf.

AGENTS.md Instructions

Anita automatically includes AGENTS.md guidance in the system prompt when it builds context for a chat session.

Discovery order:

1. Global defaults from ~/.anita/AGENTS.md
2. Repository instructions from <repo-root>/AGENTS.md

When both files exist, repository instructions are placed after global instructions and override them when they conflict.

Create a global instructions file:

anita agents init --global

Create a repository instructions file at the Git repository root, or in the current directory when outside Git:

anita agents init

Use --force with either command to overwrite an existing file.

Context Compaction

Anita tracks an approximate context budget for each session. When the model context reaches a high-water mark for the selected model's context window, Anita folds older history into a rolling summary while keeping a recent token-budgeted tail, including recent tool calls and tool results, available verbatim.

By default, compaction starts around 80% of the usable model context window after reserving response tokens, preserves roughly 24,000 recent tokens, and skips compaction when the older prefix is too small to reduce context meaningfully.

Ollama Cloud

Use a supported Ollama Cloud model with the ollama-cloud/ provider. This is separate from the local ollama/ provider, which still targets a local Ollama daemon.

export OLLAMA_API_KEY=<your-ollama-api-key>
anita chat "Your message here" --model ollama-cloud/glm-5.2

Supported Ollama Cloud models:

• ollama-cloud/glm-5.2
• ollama-cloud/minimax-m3 [images, files]
• ollama-cloud/deepseek-v4-pro
• ollama-cloud/kimi-k2.7-code [images]

Ollama Cloud requests use an explicit max_tokens value of 8192 so the provider leaves context room for the prompt.

Cloudflare AI Gateway

Use the cloudflare-ai-gateway/ provider for supported Workers AI models routed through Cloudflare AI Gateway.

export CLOUDFLARE_ACCOUNT_ID=<your-cloudflare-account-id>
export CLOUDFLARE_API_TOKEN=<your-cloudflare-api-token>
export CLOUDFLARE_AI_GATEWAY_ID=<your-gateway-id> # optional, defaults to default
anita chat "Your message here" --model cloudflare-ai-gateway/@cf/zai-org/glm-4.7-flash

Supported Cloudflare AI Gateway models matched from the Ollama local and Ollama Cloud model lists:

• cloudflare-ai-gateway/@cf/zai-org/glm-4.7-flash
• cloudflare-ai-gateway/@cf/zai-org/glm-5.2
• cloudflare-ai-gateway/minimax/m3
• cloudflare-ai-gateway/deepseek/deepseek-v4-pro
• cloudflare-ai-gateway/@cf/moonshotai/kimi-k2.7-code [images]
• cloudflare-ai-gateway/@cf/google/gemma-4-26b-a4b-it [images]

The local qwen3.5:35b-a3b-coding-nvfp4 model is not listed because Cloudflare's Workers AI catalog does not currently expose that exact model.

JSON Event Streaming

Use --stream-json to emit one JSON event per line for machine-readable integrations:

anita chat "Add a hello world script" --stream-json

Example stream:

{"type":"run.started","sessionId":"9e6f8a7d-7ff1-4c2c-b3d8-9c3ed5a1d4b7","model":"ollama/glm-4.7-flash:latest","workingDirectory":"/path/to/project","timestamp":"2026-04-09T15:00:00.000Z"}
{"type":"assistant.reasoning","text":"I should inspect the project structure before changing files."}
{"type":"assistant.text","text":"I added a hello world script."}
{"type":"tool.call","id":"toolu_123","name":"write_file","input":{"path":"hello.js","content":"console.log(\"hello world\");\n"}}
{"type":"tool.result","id":"toolu_123","name":"write_file","content":"File written successfully.","isError":false}
{"type":"run.completed","sessionId":"9e6f8a7d-7ff1-4c2c-b3d8-9c3ed5a1d4b7","status":"completed","stopReason":"end_turn","timestamp":"2026-04-09T15:00:01.000Z"}

Approvals in --stream-json mode

When a tool call requires approval (policy returns ask), the CLI emits two extra events around the gate so consumers can audit decisions. They fire in every mode — including --auto-approve and human TTY mode — so the stream shape is uniform regardless of how the answer was produced.

{"type":"approval.request","id":"toolu_123","tool":"run_command","input":{"command":"npm test"},"timestamp":"…"}
{"type":"approval.resolved","id":"toolu_123","approved":true,"reason":"user","timestamp":"…"}

id is the model's tool call id and matches the surrounding tool.call / tool.result lifecycle. input is the structured object, never a pre-rendered string. reason is one of:

• user — the responder answered.
• aborted — the run's AbortSignal fired while waiting.
• eof — the consumer closed stdin before answering.
• error — the approval callback itself threw.

When stdin is a pipe, the CLI never writes a prompt to stdout or stderr. The consumer answers by writing a single JSON line to stdin:

{"type":"approval.response","id":"toolu_123","approved":true}

The resolver waits silently on stdin. Mismatched ids, malformed JSON, and unknown message types are discarded (logged to stderr) so a stale response can't poison the run. There is exactly one approval pending at a time — the executor runs tool calls sequentially.

Without --stream-json, the CLI uses the normal human-readable terminal output.

When using an OpenAI-compatible backend that exposes reasoning traces, Anita will also store them in the assistant_response event payload as reasoning and emit an assistant.reasoning stream event.

Publishing

To publish the package to npm under the @germanescobar scope:

# Log in to npm
npm login

# Build and publish the public scoped package
npm publish --access public

After publishing, users can install it with:

npm install -g @germanescobar/anita

Architecture

The Coding Agent is built with a modular architecture:

Core Components

• Agent Loop - Manages the conversation cycle, including message handling and tool execution
• Context Builder - Separates stable agent instructions from dynamic environment context
• Executor - Executes AI-generated tool calls with safety policies
• Provider - Abstracts OpenAI-compatible AI model interactions
• Tool Registry - Manages available tools and their schemas

Storage Layer

• Event Store - Persist all interactions and events
• Session Store - Save and retrieve conversation sessions

Tools

• read-file - Read file contents
• write-file - Create or overwrite files
• edit-file - Edit existing files with precise replacements
• run-command - Execute shell commands (with approval)

Project Structure

coding-agent/
├── src/
│   ├── agent/
│   │   ├── context-builder.ts    # Builds static prompts and dynamic context
│   │   ├── executor.ts            # Executes tool calls safely
│   │   ├── loop.ts                # Main conversation loop
│   │   ├── policies.ts            # Safety and approval policies
│   │   └── session.ts             # Session management
│   ├── cli/
│   │   └── index.ts               # Command-line interface
│   ├── models/
│   │   ├── anthropic.ts           # Anthropic Claude provider implementation
│   │   ├── openai.ts              # OpenAI-compatible provider implementation
│   │   ├── provider.ts            # AI provider abstraction
│   │   └── resolve.ts             # Provider factory
│   ├── storage/
│   │   ├── event-store.ts         # Persistent event store
│   │   └── session-store.ts       # Persistent session store
│   ├── tools/
│   │   ├── edit-file.ts           # Edit file tool
│   │   ├── read-file.ts           # Read file tool
│   │   ├── registry.ts            # Tool registry and schema generation
│   │   └── run-command.ts         # Command execution tool
│   ├── types/
│   │   ├── agent.ts               # Agent type definitions
│   │   ├── events.ts              # Event types
│   │   ├── messages.ts            # Message type definitions
│   │   └── tools.ts               # Tool type definitions
│   ├── CLI.ts
│   └── index.ts
├── package.json
├── tsconfig.json
└── README.md

How It Works

1. User sends a message via the CLI
2. Context is built based on the current working directory and conversation history
3. AI model processes the message and determines if tools are needed
4. Tool execution happens if needed (safely with approval prompts)
5. Results are passed back to the AI for further processing
6. Final response is displayed to the user
7. Session is saved with all messages and events

API Compatibility

Available providers (provider/model format):

• ollama/<local-model>
• ollama-cloud/glm-5.2
• ollama-cloud/minimax-m3
• ollama-cloud/deepseek-v4-pro
• ollama-cloud/kimi-k2.7-code
• cloudflare-ai-gateway/@cf/zai-org/glm-4.7-flash
• cloudflare-ai-gateway/@cf/zai-org/glm-5.2
• cloudflare-ai-gateway/minimax/m3
• cloudflare-ai-gateway/deepseek/deepseek-v4-pro
• cloudflare-ai-gateway/@cf/moonshotai/kimi-k2.7-code
• cloudflare-ai-gateway/@cf/google/gemma-4-26b-a4b-it
• openrouter/z-ai/glm-5.1
• openrouter/minimax/minimax-m3
• openrouter/deepseek/deepseek-v4-pro
• openrouter/moonshotai/kimi-k2.6

ollama/<local-model> targets http://localhost:11434/v1. ollama-cloud/<model> targets Ollama Cloud and uses OLLAMA_API_KEY. cloudflare-ai-gateway/<model> targets Cloudflare AI Gateway and uses CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN, and optional CLOUDFLARE_AI_GATEWAY_ID. openrouter/<model> targets OpenRouter and uses OPENROUTER_API_KEY.

Configuration

Session data is stored in the .anita/ directory in your working directory:

.anita/
├── events/          # Individual event logs
│   └── <session-id>/
└── sessions/        # Session metadata
    └── <session-id>

For backward compatibility, Anita falls back to the legacy .coding-agent/ directory when it contains existing sessions and .anita/ does not.

Development

# Run the CLI in development mode
npm run dev -- chat "Create a simple React component that displays a greeting"

# Build for production
npm run build

# Run the built CLI without installing it globally
npm run start -- chat "Create a simple React component that displays a greeting"

Safety Considerations

• All shell commands require explicit approval before execution
• Tool results are previewed before being shown to the AI
• File modifications can be reviewed via event logs
• Maximum iteration limit prevents infinite loops (default: 50)

License

MIT

Contributing

Contributions are welcome! Feel free to submit issues and pull requests.