agentic

A four-stage AI pipeline that takes a plain-text task description and produces a fully implemented codebase. Run it from any project directory.

Installation

Download a pre-built binary

Go to the Releases page and download the archive for your platform.

macOS (Apple Silicon)

curl -L https://github.com/tsurai/agentic-framework/releases/latest/download/agentic-v<VERSION>-darwin-arm64.tar.gz | tar xz
sudo mv agentic /usr/local/bin/

macOS (Intel)

curl -L https://github.com/tsurai/agentic-framework/releases/latest/download/agentic-v<VERSION>-darwin-amd64.tar.gz | tar xz
sudo mv agentic /usr/local/bin/

Linux (amd64)

curl -L https://github.com/tsurai/agentic-framework/releases/latest/download/agentic-v<VERSION>-linux-amd64.tar.gz | tar xz
sudo mv agentic /usr/local/bin/

Windows (amd64)

Download agentic-v<VERSION>-windows-amd64.zip from the Releases page, extract agentic.exe, and place it in a directory on your PATH.

Build from source

Requires Go 1.26 or later.

git clone https://github.com/tsurai/agentic-framework
cd agentic-framework
make install

make install copies the binary to /usr/local/bin/agentic. On Windows, run go build -o agentic.exe ./cmd and move the file to a directory on your PATH.

Quick start

With Cursor (no separate API key needed)

If you have Cursor installed and are signed in, just run:

agentic -i "Build a REST API for user management in Go"

The -i flag opens an interactive model picker. Select cursor as the provider for each role and pick your models. Your Cursor access token is read automatically from Cursor's local database — no setup required.

With Anthropic

export ANTHROPIC_API_KEY=sk-ant-...
agentic "Build a REST API for user management in Go"

With Ollama (fully local, no keys)

ollama pull qwen2.5-coder:7b
agentic -i "Build a REST API for user management in Go"
# select "ollama" for each role

Interactive model selection

Run with -i to pick models before the pipeline starts:

agentic -i "Build a REST API for user management"

You will see a menu for each role (Planner, Coder, Reviewer) where you can select a provider and a model. If you select custom, you can type any model name and base URL manually. The selection applies only to the current run and does not modify config.yaml.

Cursor provider

The cursor provider uses your Cursor subscription to access models — the same models available in the Cursor editor — with no separate API key.

How it works: the token is read from Cursor's local SQLite database (state.vscdb) automatically, so you only need to be signed into Cursor. sqlite3 must be installed (pre-installed on macOS; sudo apt install sqlite3 on Linux). Alternatively, set the token manually:

export CURSOR_ACCESS_TOKEN=$(sqlite3 \
  ~/Library/Application\ Support/Cursor/User/globalStorage/state.vscdb \
  "SELECT value FROM ItemTable WHERE key='cursorAuth/accessToken'")

Models available through Cursor's subscription:

Model	Notes
claude-3-5-sonnet-20241022	Smart, good for planning
claude-3-5-haiku-20241022	Fast, good for coding
gpt-4o	Balanced
gpt-4o-mini	Cheap and fast
o3-mini	Reasoning
cursor-small	Cursor's own model, very fast
gemini-2.0-flash	Fast, low cost

The cursor provider uses https://api2.cursor.sh as the API endpoint with an OpenAI-compatible request format. This relies on Cursor's internal API which is not publicly documented and may change. Set base_url in the role config to override the endpoint if needed.

Configuration

Create a config.yaml in the directory you work from, or place a global one at ~/.config/agentic/config.yaml. The binary searches in that order:

1. Path given by -config flag
2. ./config.yaml in the current working directory
3. ~/.config/agentic/config.yaml
4. Built-in defaults

An example config.yaml is included in every release archive.

Anthropic models (default)

models:
  planner:
    model: "claude-opus-4-6"
    provider: "anthropic"

  coder:
    model: "claude-haiku-4-5-20251001"
    provider: "anthropic"

  reviewer:
    model: "claude-sonnet-4-6"
    provider: "anthropic"

Set the key before running:

export ANTHROPIC_API_KEY=sk-ant-...

Ollama — local models, no API key

Install Ollama from https://ollama.com, pull the models you want, then update your config:

ollama pull qwen2.5-coder:32b
ollama pull qwen2.5-coder:7b
ollama pull qwen2.5-coder:14b

models:
  planner:
    model: "qwen2.5-coder:32b"
    provider: "openai"
    base_url: "http://localhost:11434/v1"

  coder:
    model: "qwen2.5-coder:7b"
    provider: "openai"
    base_url: "http://localhost:11434/v1"

  reviewer:
    model: "qwen2.5-coder:14b"
    provider: "openai"
    base_url: "http://localhost:11434/v1"

No api_key is needed for Ollama.

Any OpenAI-compatible provider

Set provider: "openai" and point base_url at the provider endpoint:

Provider	base_url
OpenAI	https://api.openai.com/v1
Groq	https://api.groq.com/openai/v1
LM Studio	http://localhost:1234/v1
Ollama	http://localhost:11434/v1

Mixing providers

You can use a different provider for each role, for example a smart cloud model for planning and a free local model for the bulk of the coding:

models:
  planner:
    model: "claude-opus-4-6"
    provider: "anthropic"

  coder:
    model: "qwen2.5-coder:7b"
    provider: "openai"
    base_url: "http://localhost:11434/v1"

  reviewer:
    model: "claude-sonnet-4-6"
    provider: "anthropic"

Full config reference

pipeline:
  max_coder_workers: 4      # parallel coder agents
  output_dir: "."           # where generated source files are written
  max_review_iterations: 3  # plan review loops before proceeding

project:
  language: "go"            # context passed to planner and coders
  framework: ""             # e.g. "gin, gorm"
  description: ""           # extra project context

output:
  verbose: true             # print plan summaries and review text
  save_plan: true           # write plan.md and review.md to plans/

Usage

agentic [flags] <task description>

Flag	Default	Description
-config	auto-discover	path to config file
-output	from config	override output directory
-verbose	from config	print extra output
-skip-review	false	skip the code review stage
-i	false	interactive model selection before running
-version		print version and exit

Examples

agentic "Build a REST API for user management in Go"

agentic -config ~/work/myconfig.yaml "Add JWT auth middleware"

agentic -output ./generated -skip-review "Create a CLI tool that converts JSON to YAML"

agentic -verbose "Implement a rate limiter using the token bucket algorithm"

Pipeline stages

Task description
      |
      v
  1. Planner        Smart model generates a structured implementation plan.
                    Saved to ./plans/<date>-<slug>/plan.md.
      |
      v
  2. Plan Review    Same model reviews and optionally revises the plan.
                    Runs up to max_review_iterations times.
      |
      v
  3. Implement      One coder agent per task, run in parallel.
                    Tasks with dependencies or overlapping files are serialised
                    automatically. Uses a cheap, fast model.
      |
      v
  4. Code Review    Mid-tier model reviews all generated files.
                    Result saved to ./plans/<date>-<slug>/review.md.

Plans folder

Every run creates a timestamped directory under plans/ in the current working directory:

plans/
  2026-03-28-build-rest-api-for-user/
    plan.md      the approved implementation plan
    review.md    the code review output

The directory name is <YYYY-MM-DD>-<first-6-words-of-task>. These files are meant to be committed alongside your code so you have a record of what was generated and why.

How parallelism works

The planner assigns each task a list of files it will write and a list of dependencies. The scheduler enforces two rules before dispatching a task:

1. All dependency tasks must have completed.
2. No currently running task may claim any of the same file paths.

Independent tasks — separate packages, separate layers — run simultaneously up to max_coder_workers. Tasks that share files or depend on each other's output are serialised automatically.

Exit codes

Code	Meaning
0	Success, code review passed
1	Hard error (planning failed, API error, etc.)
2	Pipeline completed but code review found issues

Releasing a new version

Tag a commit and push:

git tag v1.0.0
git push origin v1.0.0

GitHub Actions builds binaries for all platforms and creates a release with attached archives and a checksums.txt file.