An autonomous software engineering agent that reads tasks, implements them in your codebase, writes tests, validates its work, and opens pull requests — while you sleep.
Give it a backlog. Wake up to PRs.
Agentic Coder connects to your task source (markdown files, Jira, or Notion), picks up tasks, and for each one:
- Explores the codebase to understand the relevant code
- Plans the approach (visible in the terminal output)
- Implements the changes with minimal, precise edits
- Tests — runs existing tests, writes new ones when appropriate
- Validates — runs linters and type checkers, fixes any errors it introduced
- Self-reviews — checks its own
git diffbefore committing - Ships — creates a branch, commits, pushes, and opens a PR with a full description
If tests fail, it iterates up to 3 times to fix the issue.
[Task Source] [Agent Pipeline] [Output]
Markdown (.md) ─┐ 1. Explore codebase Branch
Jira API ─┼─→ Adapter → 2. Plan approach → Claude → Commit
Notion API ─┘ 3. Implement (tool Push
4. Test use) PR on GitHub
5. Validate Session log
6. Self-review
7. Ship
git clone https://github.com/Open-Earth-Foundation/agentic-coder.git
cd agentic-coder
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # add your Anthropic API keyEdit .env with your configuration, then:
./run.sh list # see available tasks
./run.sh task 1 # run task 1 → creates PR
./run.sh all # run all tasksWrite tasks in a markdown file under tasks/, then run them:
./run.sh list # list tasks
./run.sh task 1 # run one task
./run.sh all # run all tasks
./run.sh dry # dry run (no changes)
TASKS_FILE=tasks/my-sprint.md ./run.sh all # use a different fileConnect to your Jira board and let the agent pick up labeled issues:
# Add JIRA_* credentials to .env, then:
./run.sh jiraThe agent will fetch issues labeled agent-ready, move them to "In Progress", implement the fix, open a PR, and post the PR link as a comment on the Jira issue.
Same idea, but from a Notion database:
# Add NOTION_* credentials to .env, then:
./run.sh notionConnect to your Linear workspace and let the agent pick up labeled issues:
# Add LINEAR_* credentials to .env, then:
./run.sh linearThe agent will fetch issues labeled agent-ready, move them to "In Progress", implement the fix, open a PR, and post the PR link as a comment on the Linear issue.
Automatically score and estimate new Linear issues:
./run.sh estimate # continuous polling (every 120s)
./run.sh estimate --once # single pass then exitThe estimator polls for issues without estimates, uses Claude to analyze complexity and impact, then posts a formatted suggestion (T-shirt size + rationale) as a comment. Engineers confirm via Shift+E.
Let the agent find and fix issues on its own:
./run.sh scanIt scans the repo for TODO/FIXME comments, leftover console.log statements, as any type assertions, and empty catch blocks — then generates tasks and fixes them.
The "assign tasks and go to sleep" mode:
./run.sh watch jira # poll Jira every 2 minutes
./run.sh watch notion # poll Notion every 2 minutes
./run.sh watch linear # poll Linear every 2 minutesWhen tasks are found, it processes them. When idle for 5 cycles, it runs a repo scan and fixes what it finds. Ctrl+C to stop.
After the agent finishes its work, an optional evaluator pass runs a second Claude call to review the diff. It checks whether the change is minimal, correct, tested, and safe to merge. If it fails, the agent gets one more iteration to fix the issues.
The evaluator is enabled by default. Disable it in config with enable_evaluator: False.
View a summary of all past runs:
python -m agent_factory reportShows total tasks run, success rate (tasks that produced a PR), total estimated cost, and a list of recent PRs.
Every completed task is logged to logs/ with the full summary, PR URL, and cost:
./run.sh logsTasks live in tasks/*.md. Each ## heading is a task:
## Fix the login performance issue
- **type**: bugfix
- **description**: Remove the unnecessary User.findAll() call in auth.ts
- **files**: app/src/lib/auth.ts
### Acceptance criteria
- The findAll() call is removed
- Login still works correctlySupported fields:
| Field | Required | Description |
|---|---|---|
## Title |
Yes | Used to generate branch names |
**type** |
No | bugfix, feature, improvement, cleanup |
**description** |
No | What needs to be done |
**files** |
No | Comma-separated list of relevant files |
### Acceptance criteria |
No | Bullet list of requirements the agent will verify |
The agent has 6 tools it can call during its loop:
| Tool | What it does |
|---|---|
read_file |
Read any file in the repo (with line numbers) |
search_code |
Regex search across the codebase (via ripgrep) |
list_directory |
Explore the repo structure |
find_files |
Find files by name pattern (via find) |
edit_file |
Precise string replacement in files |
run_command |
Git operations, linting, testing, type checking |
The agent automatically reads project-specific context from the repo:
README.md— understands the project.cursor/rules/*.md— follows team conventions.cursor/skills/*/SKILL.md— knows project patternsAGENTS.md,CONTRIBUTING.md— follows contribution guidelines
This context is injected into the system prompt so the agent writes code that fits the project's style.
Each task source has an adapter that handles the full lifecycle:
| Adapter | Fetch tasks | On start | On complete |
|---|---|---|---|
| Markdown | Parses ## headings |
— | — |
| Jira | Queries by label | Moves to "In Progress" | Posts PR link as comment |
| Notion | Queries by status | Sets "In Progress" | Sets "Done" + adds comment |
| Linear | Queries by label (agent-ready) |
Moves to "In Progress" | Posts PR comment + moves to "In Review" |
Before running, the agent verifies:
- Git repo exists and is on the correct base branch
- Working tree is clean (no uncommitted changes)
ghCLI is authenticated- Remote repository is reachable
Each task shows token usage and estimated cost:
API calls: 17 | Tokens: 93,432 in / 2,877 out | Est. cost: $0.32
Costs are also saved in session logs.
All configuration lives in .env:
# Required
ANTHROPIC_API_KEY=sk-ant-...
REPO_PATH=../your-repo
BRANCH_PREFIX=agentic-coder
BASE_BRANCH=develop
# Linear (recommended — primary integration)
LINEAR_API_KEY=lin_api_...
LINEAR_TEAM_ID=your-team-uuid
LINEAR_AGENT_LABEL=agent-ready
# Jira (optional — legacy, kept for backward compat)
JIRA_DOMAIN=yourcompany.atlassian.net
JIRA_EMAIL=you@company.com
JIRA_API_TOKEN=your-token
JIRA_PROJECT=CC
JIRA_AGENT_LABEL=agent-ready
# Notion (optional)
NOTION_API_KEY=secret_...
NOTION_DATABASE_ID=your-database-idA read-only Next.js dashboard at apps/analytics/ showing live engineering metrics:
- Sprint velocity (points per cycle)
- Pipeline status (issue distribution)
- Cost per initiative (implied from estimates)
- Estimation accuracy (AI vs actual)
- DORA metrics (coming soon)
cd apps/analytics
cp .env.example .env.local # add LINEAR_API_KEY + ADMIN_PASSWORD
npm install && npm run dev # -> http://localhost:3000agentic-coder/
├── AGENTS.md # Agent brief (read first)
├── CLAUDE.md # Extra context for Claude Code
├── run.sh # CLI wrapper (agent, linear, estimate, watch, scan)
├── .env / .env.example # Configuration
├── .cursor/
│ ├── rules/ # Cursor rules (general, architecture, security, …)
│ └── skills/ # Named workflows (commit-message-standards, pull-request-standards)
├── apps/
│ └── analytics/ # OEF Analytics dashboard (Next.js)
│ ├── app/api/linear/ # Linear data API route
│ ├── app/api/auth/ # Password auth
│ ├── app/page.tsx # Dashboard (velocity, ROI, pipeline, costs)
│ └── middleware.ts # Auth middleware
├── profiles/ # Per-target-repo defaults (citycatalyst, global-data, agentic-coder)
├── prompts/
│ └── system-base.md # Reference for the live system prompt
├── tasks/ # Markdown task backlogs
│ ├── getting-started.md
│ ├── citycatalyst-stability.md
│ ├── global-data-cleanup.md
│ └── self-improvement.md
├── docs/
│ ├── PLAYBOOK.md # How to operate (overnight, watch, scan)
│ └── EXTENDING.md # How to add adapters, tools, scanner rules
├── logs/ # Session logs (gitignored)
└── agent_factory/ # Core package
├── main.py # CLI entry point
├── agent.py # Agentic loop + cost tracking
├── config.py # .env loading + config
├── context.py # Project context injection
├── scanner.py # Autonomous repo scanner
├── watcher.py # Continuous polling loop
├── preflight.py # Pre-flight checks
├── task_parser.py # Task dataclass + markdown parser
├── evaluator.py # Evaluator pass (diff review)
├── tools.py # 6 agent tools
└── adapters/
├── base.py # TaskAdapter interface
├── markdown.py # Markdown file adapter
├── jira.py # Jira REST API adapter
└── notion.py # Notion API adapter
- Agentic loop with Claude tool use (read, search, edit, run commands)
- Markdown task parsing
- Git workflow automation (branch, commit, push, PR via
gh) - Jira adapter with full lifecycle (fetch, status update, PR comment)
- Notion adapter with full lifecycle
- Autonomous repo scanner (TODOs, console.log,
as any, empty catch) - Watch mode (continuous polling + idle scanning)
- Project context injection (rules, skills, README)
- Pre-flight checks (git, gh auth, clean tree, remote)
- Cost tracking (tokens + USD per task)
- Session logging
- Testing loop (run existing tests, write new ones)
- Self-validation (linter, type checker, self-review)
- Evaluator pass (second Claude review of the diff before merge)
- Report command (session log summary with success rate and cost)
- Error resilience (retry with backoff on rate limits / 5xx)
- Linear adapter
- Multi-repo support (run across multiple repositories)
- GitHub Issues adapter (fetch issues labeled
agent-ready) - Slack notifications (post PR links to a channel)
- Configurable LLM (OpenAI, local models via Ollama)
- Parallel task execution
- Web dashboard for monitoring runs and costs
- MCP server integration for richer tool use
- Custom scanner rules (configurable patterns per project)
AGENTS.md— agent brief; read first if you're an AI agent or new contributor.CLAUDE.md— extra context for Claude Code-style sessions.docs/PLAYBOOK.md— operator guide: overnight runs, watch mode, scan, Cloud Agents.docs/EXTENDING.md— how to add adapters, tools, scanner rules, profiles.profiles/— per-target-repo defaults (CityCatalyst, global-data, agentic-coder).prompts/system-base.md— reference for the live system prompt.tasks/— curated task backlogs (citycatalyst-stability, global-data-cleanup, self-improvement).
Most AI coding tools are either:
- Too generic — they don't know your project's conventions, rules, or architecture
- Too closed — you can't control the prompt, tools, or workflow
- Too manual — you still have to babysit every step
Agentic Coder is yours to own and customize. It reads your project's rules, follows your conventions, and you control every aspect of how it works. It's the difference between hiring a generic contractor and having a team member who knows the codebase.
AGPL-3.0 — see LICENSE.