# 🤖 AI Coding Agent
**An autonomous coding agent that reads a Git repository, understands the
codebase, plans changes, edits files, runs tests, fixes its own failures,
creates a commit, and generates a PR description.**
[](https://github.com/sajankoira/ai-coding-agent/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.typescriptlang.org/)
[](https://www.python.org/)
[](https://nodejs.org/)
[](CONTRIBUTING.md)
**Language stack:** TypeScript (agent orchestration + tooling) · Python
(AST analysis + test runner) · PostgreSQL (run persistence) · Docker
(deployment) · OpenAI-compatible LLM API (reasoning).
**Language stack:** TypeScript (agent orchestration + tooling) · Python
(AST analysis + test runner) · PostgreSQL (run persistence) · Docker
(deployment) · OpenAI-compatible LLM API (reasoning).
```
User
│
▼
Agent CLI ─── LLM (OpenAI / mock)
│ │
├── Analyzer (Python AST) ├── code editing
├── Planner (LLM) ├── terminal (sandboxed)
├── File Search (regex) ├── test runner (auto-detect)
├── Git Manager (status/diff/commit) ─── GitHub PR
└── Store (PostgreSQL / JSONL)
```
---
## Quick start (real LLM)
```bash
# 1. Install
git clone https://github.com/sajankoira/ai-coding-agent
cd ai-coding-agent
npm install
npm run build
# 2. Set your LLM API key
cp .env.example .env
# edit .env → LLM_API_KEY, optionally LLM_BASE_URL, LLM_MODEL
# 3. Run
node dist/cli.js --repo /path/to/your/repo --task "Add input validation to the login handler"
```
## Why?
Most "AI coding tools" are chatbots that *talk* about code. This is an agent
that actually **does the work**: it reads the repo, plans, edits, runs your
tests, reads the failures, fixes its own mistakes, commits, and drafts a PR —
then hands you the diff to review. It's a pipeline you can inspect, extend,
and deploy, not a black box.
## Offline demo (no API key needed)
A deterministic **mock brain** stands in for the LLM — you can see the
entire pipeline work without any network or API key:
```bash
npm run build
bash scripts/demo.sh
```
The demo:
1. Creates a fresh git repo (`example-repo/`) containing a small calculator
library with two arithmetic bugs.
2. Runs the agent (mock mode, plan-first, commit, dry-run PR).
3. The agent: analyzes the repo → runs tests → finds `add` and `multiply`
return the wrong results → reads the source → edits both functions →
re-runs tests (green!) → commits → generates a PR body.
4. Prints the final summary and the artifact path.
Expected output (last lines):
```
Run summary
────────────────────────────
Run id: run-2026-08-16T10-30-00-xxxx
Tool calls: 14 (13 ok)
Steps: 16
PR body: /path/.agent/runs/.../PR_DESCRIPTION.md
```
Open the PR body file — it contains a real PR description generated from
the diff, exactly as the pipeline would produce with a real LLM.
## Options
```
coding-agent --repo
--task "" [options]
--repo Git repository to work on (default: cwd)
--task Task description (required)
--mock Use the offline deterministic brain
--model LLM model (env LLM_MODEL)
--base-url OpenAI-compatible endpoint (env LLM_BASE_URL)
--api-key API key (env LLM_API_KEY)
--plan-first Build a step plan before the agent loop
--commit Commit the agent's changes when done
--pr Create / dry-run the PR (default: none)
--branch Create a working branch
--max-iterations Loop cap (default 30)
--verbose Print every agent step
--db / --no-db Force PostgreSQL / JSONL store
-h Help
```
## Architecture
A detailed architecture document is at [`ARCHITECTURE.md`](/ai-coding-agent/ARCHITECTURE.html).
### Key design decisions
| Decision | Rationale |
|----------|-----------|
| **TypeScript orchestration** | Fast iteration, strong typing, Node 18+ has `fetch` natively. |
| **Python for analysis/tests** | Real `ast` module for Python parsing; mature test runners. |
| **Docker + PostgreSQL** | Requested in spec; JSONL fallback keeps demos zero-setup. |
| **OpenAI-compatible LLM client** | Works with OpenAI, Groq, Together, DeepSeek, Ollama, LM Studio, vLLM. |
| **MockBrain** | A hand-coded state machine that exercises the full pipeline offline. |
| **edit_file (search‑replace)** | Safer and more robust than line-number patches; LLM communicates the *content* it wants to change. |
| **Safety blocklist** | `rm -rf /`, `sudo`, `git push --force`, etc. are rejected before execution. |
## Extending
- **Add a new tool**: create `src/tools/my-tool.ts`, export a `Tool` matching
the interface, and add it to `src/tools/registry.ts`.
- **New LLM provider**: implement the `LLMClient` interface from
`src/llm/types.ts` and swap it in `src/cli.ts`.
- **New store backend**: implement the `Store` interface from
`src/store/index.ts`.
## Roadmap
- Interactive "approve each edit" mode
- Web UI (React dashboard for run history / logs)
- Built-in tree‑sitter for exact syntax-aware search
- GitHub App integration (react on issues)
---
Built as a proof of what an AI coding agent can be — not just a chatbot.