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, 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/ada

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

ada 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 ada command globally from this checkout
npm link

After that, the ada 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:

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

Resume a Session

Continue from a previous conversation:

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

List Past Sessions

ada sessions

View Event Logs

View detailed events for a specific session:

ada events <session-id>

List Supported Models

Show the built-in model choices grouped by provider:

ada 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/.

Custom Model

Use a different AI model:

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

AGENTS.md Instructions

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

Discovery order:

1. Global defaults from ~/.ada/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:

ada agents init --global

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

ada agents init

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

Context Compaction

Ada tracks an approximate context budget for each session. When the model context reaches a high-water mark for the selected model's context window, Ada 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>
ada chat "Your message here" --model ollama-cloud/glm-5.1

Supported Ollama Cloud models:

• ollama-cloud/glm-5.1
• ollama-cloud/minimax-m2.7
• ollama-cloud/deepseek-v4-pro
• ollama-cloud/kimi-k2.6

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

JSON Event Streaming

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

ada 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"}

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

When using an OpenAI-compatible backend that exposes reasoning traces, Ada 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/ada

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.1
• ollama-cloud/minimax-m2.7
• ollama-cloud/deepseek-v4-pro
• ollama-cloud/kimi-k2.6
• openrouter/z-ai/glm-5.1
• 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. openrouter/<model> targets OpenRouter and uses OPENROUTER_API_KEY.

Configuration

Session data is stored in the .coding-agent/ directory in your working directory:

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

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.