KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #open-source #ai #claude-code #codex #deepseek-harness #dsh-plugin #react #windows #developer-tools

Agena

★ 97 Open GitHub ↗

Agentic AI platform with pixel agent technology — autonomous code generation, PR automation & multi-tenant SaaS

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Sponsor AGENA](https://img.shields.io/badge/Sponsor-AGENA-ff69b4?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/aozyildirim)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://raw.githubusercontent.com/aozyildirim/Agena/main/LICENSE)
[![Website](https://img.shields.io/badge/Website-agena.dev-0d9488)](https://agena.dev)

# AGENA — Agentic AI Platform for Autonomous Code Generation

> **The open-source agentic AI platform that writes code, reviews quality, and ships pull requests autonomously.**

AGENA is a production-ready, multi-tenant **agentic AI** orchestration platform. It coordinates LLM-powered agents to analyze tasks, generate code, review changes, and create pull requests — fully autonomously. Built as a **monorepo with 6 pip-installable packages**.

### Why AGENA?

- 🔑 **No API keys, no per-token billing** — AGENA runs on your existing **Claude Code / Codex CLI** subscription locally via a host bridge. Your plan does the work; nothing is metered per token.
- 🔁 **The full loop, autonomously** — production error (Sentry / New Relic) → task → AI fix → **pull request** → merge → issue auto-resolved.
- 🧩 **Where your work already lives** — Sentry, New Relic, Jira, YouTrack, Azure DevOps, GitHub. Pulls real sprint items and ships real PRs.
- 🔒 **Self-hostable & multi-tenant** — your code and repos stay on your own infrastructure (bring-your-own runtime).

## Demo

<p align="center">
  <sub><b>Zero to fully-loaded in under a minute</b> — sign up, complete onboarding, switch on every integration, then explore Boss Mode, the agent roster, and visual flows.</sub>
  <br/>
  <sub>▶ <a href="frontend/public/readmeimg/demo-tour.mp4">Watch the narrated product tour</a> — every module in ~5 min, with voiceover + captions · <a href="frontend/public/readmeimg/demo.mp4">first-run MP4</a></sub>
</p>

---

<table align="center">
  <tr>
    <td align="center" width="640">
      <h3>❤️ Sponsor AGENA</h3>
      <p>
        AGENA is built and maintained in the open by a small team. If it
        ships PRs for your team, consider sponsoring — every tier helps
        keep the project independent, ad-free, and moving fast.
      </p>
      <p>
        <a href="https://github.com/sponsors/aozyildirim">
          <img src="https://img.shields.io/badge/Sponsor%20on%20GitHub-ea4aaa?style=for-the-badge&logo=githubsponsors&logoColor=white" alt="Sponsor on GitHub" />
        </a>
      </p>
      <sub>github.com/sponsors/aozyildirim · MIT-licensed forever</sub>
    </td>
  </tr>
</table>

---

## Table of Contents

- [Why AGENA?](#why-agena)
- [Demo](#demo)
- [Key Features](#key-features)
- [Architecture](#architecture)
- [Monorepo Package Structure](#monorepo-package-structure)
- [Tech Stack](#tech-stack)
- [Quick Start](#quick-start)
- [Environment Variables](#environment-variables)
- [Docker Services](#docker-services)
- [Local Development](#local-development)
- [Database Migrations](#database-migrations)
- [Frontend Deploy (Zero-Downtime)](#frontend-deploy-zero-downtime)
- [API Endpoints](#api-endpoints)
- [AI Pipeline](#ai-pipeline)
- [Screenshots](#screenshots)
- [Contributing](#contributing)

---

## Key Features

**AI Pipeline**
- Autonomous PM → Planner → Developer → Reviewer → Finalizer workflow
- CrewAI role-based agents + LangGraph state machine orchestration
- Prompt Studio — edit system prompts at runtime without code deploy
- Vector memory (Qdrant) — learns from previous tasks for better context

**History-Grounded Sprint Refinement**
- Index closed Azure / Jira work items (with final SPs, assignees, PR
  titles, branches) into a per-org Qdrant collection
- For every new item, the LLM receives the top-5 similar past items and
  anchors its SP suggestion on your team's real distribution — naming
  which item it resembles and who did the prior work
- See [`docs/REFINEMENT.md`](docs/REFINEMENT.md) for the full flow and
  tuning knobs

**Team Skill Catalog**

Skills are AGENA's compounding-knowledge layer. Every completed task gets
distilled into a reusable pattern; every new task pulls the closest
patterns into its agent prompt. Past solutions are not re-discovered —
they get re-applied.

- **Auto extraction.** When a task completes, the Skill Librarian asks
  the LLM (Claude CLI / Codex CLI / OpenAI / Gemini, whichever you're
  using) to summarise the task's title + description + reviewed code
  into `{ name, pattern_type, tags, touched_files, approach_summary,
  prompt_fragment }`. Skipped automatically when the LLM's confidence
  is < 50%, so one-off oddities don't pollute the catalog.

- **Vector retrieval.** Each skill is embedded into Qdrant
  (org-scoped, `kind='skill'`) alongside a MySQL row that drives the
  catalog UI and usage counters.

- **Prompt injection.** Before any agent runs, the top-3 skills above
  the relevance threshold are prepended to the system prompt as a
  `RELEVANT TEAM SKILLS` block. Works in Claude CLI, Codex CLI,
  Gemini, OpenAI, and the classic CrewAI pipeline — same retrieval,
  four transports.

- **Concrete payoff.** After ~50 tasks, a Flo-sized team's catalog
  carries 20+ codebase-specific patterns:

```
  ┌─ "Stock allocator pattern" ──────────────────────────────────┐
  │  pattern_type: refactor                                       │
  │  tags: [stock, multi-site, allocation]                        │
  │  touched_files:                                               │
  │    app/Library/Stock/SiteBasedAllocator.php                   │
  │    app/Services/V1/StockService.php                           │
  │  prompt_fragment:                                             │
  │    "When site-based stock allocation is needed, use the       │
  │     SiteBasedAllocator class. Don't compute it inline — the   │
  │     allocator already handles overflow, fallback sites, and   │
  │     the per-SKU lock."                                        │
  └───────────────────────────────────────────────────────────────┘
  ```

Next time someone files a stock-related task, the agent gets that
  fragment in its prompt — no senior tap on the shoulder needed.

- **Manual edits welcome.** Hit `/dashboard/skills` and the "Yeni Skill"
  button to seed your team's pattern library directly. Useful for
  encoding "don't do this again" lessons (e.g. *"httpx `params={}`
  silently strips the URL's query string — always pass `None`"*) before
  AGENA has accumulated enough completed tasks to extract them on its
  own.

- See [`docs/SKILLS.md`](docs/SKILLS.md) for the extraction + retrieval
  flow, tuning knobs, and the comparison vs Refinement's similar-past
  index.

**Runtimes Registry**
- Every compute environment that can execute agent tasks (host CLI
  bridge, teammate's laptop, cloud daemon) registers as a Runtime
- Auto-enrollment: `bridge-server.mjs` picks up `AGENA_JWT` +
  `AGENA_TENANT_SLUG` from env and calls `/runtimes/register` on
  startup, then heartbeats every 30s with its current CLI availability
- `/dashboard/runtimes` shows the live list with status dots, CLI
  badges, heartbeat age, and daemon version
- See [`docs/RUNTIMES.md`](docs/RUNTIMES.md) for the enrollment +
  heartbeat + security model

**Multi-Repo Orchestration**
- Assign a single task to multiple repositories simultaneously
- Each repo runs its own AI pipeline in parallel — independent branches and PRs
- Per-repo locking prevents concurrent conflicts
- Unified dashboard shows all PRs and their status in one view

**Task Dependencies & Auto-Queue**
- Define execution order: Task B depends on Task A
- Worker checks dependencies before running — blocked tasks wait automatically
- When a dependency completes, dependent tasks auto-queue and start
- Cycle detection prevents circular dependency chains
- Visual dependency flow in the dashboard: A ✓ → B ✓ → C (waiting)

**DevOps Automation**
- Auto-generates branches, commits, and pull requests (GitHub + Azure DevOps)
- Sprint import from Jira, YouTrack and Azure DevOps
- DORA metrics dashboard (deployment frequency, lead time, change failure rate, MTTR)
- Team health symptom analysis (knowledge silos, bus factor, stale PRs, etc.)

**Shareable Task Links**
- One-click "Share" on any task — picks a duration (1–30 days) and a
  use cap (1–25 imports), gets back a tokenised public URL
- Recipients without an account can read the task (description, comments
  and inline images proxied through the *sender's* PAT so screenshots
  still load) and click "Import to my org" to copy the task — including
  attachments — into their own workspace
- Built-in share buttons for WhatsApp, Microsoft Teams, Slack,
  Telegram, Email and X next to the link, so the URL never has to
  leave the modal manually
- Tokens are revocable, time-limited and use-capped; expired or spent
  links return a friendly "this link is no longer active" page

**Multi-Tenant SaaS**
- Organization isolation with subdomain routing
- JWT auth + RBAC (owner, admin, member, viewer)
- Free/Pro/Enterprise plans with usage quotas
- Stripe billing integration

**AI-powered Sprint Nudges**
- Every blocked Azure DevOps or Jira work item gets a "Ping" button
- Checks the last comment timestamp — if >24h silent, fires a nudge
- LLM-generated, single-paragraph, language-picked-per-ping (7 locales)
- Pick the generator at send time: Claude CLI (subscription, via host
  bridge), Codex CLI (subscription), OpenAI, Gemini, or HAL. Claude
  CLI failures auto-fall-back to Codex CLI on the same bridge.
- Posts back with an `<at>@Display Name</at>` mention so Azure
  renders it as a real tag, plus a signed "written by Agena via
  {model}" line for transparency
- 48h cooldown + DB-persisted history prevents spam; UI badges
  already-nudged items with "Agena pinged Xh ago"

**Dashboard**
- Boss Mode — pixel-art office where you manage AI agents visually
- Visual flow builder — drag-and-drop automation pipelines
- Sprint performance tracking with risk scoring
- Real-time task monitoring with live logs and WebSocket updates
- Guided tour onboarding for new users
- 7 languages (TR, EN, ES, ZH, IT, DE, JA)

**Cross-Source Insights** *(module: `insights`, default off)*
- Correlation engine that ties PR merges + deploys + Sentry / NewRelic
  / Datadog / AppDynamics / Jira / Azure events into one timeline
- Confidence-scored clusters (0-100); ≥ 70 surfaces on
  `/dashboard/insights` with a one-sentence narrative + full timeline
- "Which deploy caused this bug?" answered in seconds — replaces the
  20-minute tab-hop during incidents
- Confirm / False positive / Undo triage; Confirm can open a one-click
  rollback PR for the suspected commit
- Poller runs every 5 minutes, no extra integration setup — re-uses
  the data the existing AGENA clients already cache
- Marketing page: [`/cross-source-insights`](https://agena.dev/cross-source-insights)

**Stale Ticket Triage** *(module: `triage`, source-side scan, AI verdicts)*
- **Source-side scan, not local mirror.** Hits Jira's
  `/rest/api/3/search/jql` (the new endpoint — the deprecated `/search`
  one is gone) with cursor pagination, and Azure DevOps WIQL across
  every project the org has access to. No internal task table fan-out
  — the truth lives at the source, and so does the scan.
- **Background task + progress polling.** Scan runs as a strong-ref
  asyncio task; the dashboard polls `/triage/scan/status` every 2s for
  per-row progress so the UI never blocks on a 10-minute crawl.
- **AI verdict per ticket.** The reviewer agent (Claude CLI / Codex
  CLI / hosted OpenAI — whichever the org configured, **never** an env
  fallback) reads title, description, last comment + ticket age and
  emits one of `close` / `snooze` / `keep` plus a one-sentence reason.
- **`source_updated_at` cache.** If a ticket's source-side timestamp
  hasn't moved since the last scan, we skip the LLM call and just
  backfill any new metadata fields. Fresh decisions only when the
  source actually changed.
- **Look-back window.** `triage_max_age_days` caps how far back the
  scan reaches — useful when you want "only the last 12 months,"
  not history all the way to 2018.
- **Filters baked in.** Source (Jira / Azure), project, state, and
  status chips. Cancelled / Won't Fix / Rejected excluded by default
  on both the WIQL query and a defensive Python filter on read.
- **Confirm-before-apply modal.** "Apply all AI suggestions" never
  fires silently — you see the count, the breakdown, and click to
  commit. Audit trail per decision in `triage_decisions`.
- Marketing page: [`/stale-ticket-triage`](https://agena.dev/stale-ticket-triage)

**Review Backlog Killer** *(module: `review_backlog`, multi-channel, AI-aware)*
- **Five nudge channels, comma-selectable.** Slack DM, WhatsApp,
  email, Telegram, and a comment posted directly on the PR thread
  itself (GitHub `pulls/{n}/comments` or Azure
  `{org}/{project}/_apis/git/repositories/{repo}/pullRequests/{n}/threads`
  — Azure URL needs the project segment, not just the repo guid).
- **AI-generated comment body, optional.** Toggle on and the reviewer
  agent reads the actual diff (GitHub `Accept: application/vnd.github.v3.diff`
  or Azure `iterations/{n}/changes`) and writes a polite,
  diff-specific question — not a generic "still around?" template.
- **Comment language picker — 7 languages.** Set the org's preferred
  tone in `nudge_comment_language` (en/tr/de/es/it/ja/zh); both
  static templates and the AI prompt swap accordingly.
- **Auto-nudge worker (opt-in).** Off by default —
  `backlog_auto_nudge` boolean toggle. When on, the 30-minute worker
  poller auto-posts to the configured channels with a hard 24h
  interval floor (`max(24, backlog_nudge_interval_hours)`) so nobody
  ever gets spammed by accident.
- **Azure deletion detection.** Before counting a row as "already
  nudged," we verify the existing Agena comment still lives on the
  PR. If a reviewer wiped the comment, `last_nudged_at` resets and
  the nudge becomes available again — same logic the production
  detector uses to dodge stale state.
- **Per-row cooldown that's actually delivery-aware.** Status return
  is `sent` / `rate_limited` / `comment_failed`; we only stamp
  `last_nudged_at` on `sent`, so a 400 from Azure doesn't lock the
  row for 6 hours.
- **Searchbox + chip-tag exempt-repo picker.** No more 80-row
  alt-alta toggle list. Type, autocomplete, click to add as a chip
  — same UX as Jira/Azure label pickers elsewhere in the app.
- Marketing page: [`/review-backlog-killer`](https://agena.dev/review-backlog-killer)

---

## Architecture

```
Request Flow:

Browser → Next.js Frontend (Port 3010)
     ↓
  API Request → FastAPI (Port 8010)
     ↓
  Redis Queue → Worker (background)
     ↓
  OrchestrationService → LangGraph Pipeline
     ↓
  5 Nodes: fetch_context → analyze → generate_code → review_code → finalize
     ↓
  CrewAI Agents (PM, Developer, Reviewer, Finalizer)
     ↓
  PR Creation (GitHub / Azure DevOps)
```

```
Infrastructure:

┌─────────────┐  ┌──────────┐  ┌─────────┐
  │  MySQL 8.0  │  │ Redis 7  │  │ Qdrant  │
  │  (data)     │  │ (queue)  │  │ (vector)│
  └─────────────┘  └──────────┘  └─────────┘
         ↑               ↑            ↑
  ┌──────┴───────────────┴────────────┴──────┐
  │          Python Backend                   │
  │  ┌─────────┐  ┌────────┐  ┌───────────┐ │
  │  │ API     │  │ Worker │  │ CLI Bridge│ │
  │  │ :8010   │  │ (bg)   │  │ :9876     │ │
  │  └─────────┘  └────────┘  └───────────┘ │
  └──────────────────────────────────────────┘
         ↑
  ┌──────┴──────────────┐
  │  Next.js Frontend   │
  │  Blue :3011         │
  │  Green :3012        │
  │  (Nginx LB)         │
  └─────────────────────┘
```

---

## Monorepo Package Structure

The backend is split into **6 independent, pip-installable packages**:

```
packages/
├── core/                    # agena-core
│   └── src/agena_core/
│       ├── settings.py      # Pydantic BaseSettings (67 env vars)
│       ├── database.py      # SQLAlchemy async engine + sessions
│       ├── rbac.py          # Role-based access control matrix
│       ├── plans.py         # Subscription plan definitions
│       ├── http.py          # Corporate SSL patch
│       ├── logging.py       # Logging configuration
│       ├── db/base.py       # SQLAlchemy DeclarativeBase
│       ├── security/        # JWT + bcrypt password hashing
│       └── config/          # App-wide configuration
│
├── models/                  # agena-models
│   └── src/agena_models/
│       ├── models/          # 25 SQLAlchemy ORM models
│       │   ├── user.py, organization.py, task_record.py
│       │   ├── flow_run.py, flow_assets.py
│       │   ├── git_commit.py, git_pull_request.py, git_deployment.py
│       │   ├── prompt.py, prompt_override.py
│       │   └── ... (notification, billing, usage, etc.)
│       └── schemas/         # 9 Pydantic request/response schemas
│           ├── agent.py, auth.py, task.py, github.py
│           └── ... (billing, integration, org, refinement)
│
├── services/                # agena-services
│   └── src/agena_services/
│       ├── services/        # 31 business logic modules
│       │   ├── orchestration_service.py  # Core task execution
│       │   ├── task_service.py           # Task CRUD + queue
│       │   ├── flow_executor.py          # LangGraph flow runner
│       │   ├── prompt_service.py         # DB-backed prompt loader
│       │   ├── github_service.py         # GitHub API operations
│       │   ├── azure_pr_service.py       # Azure DevOps PR creation
│       │   ├── dora_service.py           # DORA metrics calculation
│       │   ├── analytics_service.py      # Team health + analytics
│       │   ├── queue_service.py          # Redis queue management
│       │   ├── auth_service.py           # User auth + signup
│       │   ├── billing_service.py        # Stripe integration
│       │   ├── notification_service.py   # Push + in-app notifications
│       │   ├── llm/                      # LLM provider abstraction
│       │   │   ├── provider.py           # OpenAI + Gemini routing
│       │   │   ├── cost_tracker.py       # Token cost calculation
│       │   │   └── cache.py             # Redis prompt cache
│       │   └── ...
│       └── integrations/    # Third-party API clients
│           ├── azure_client.py, github_client.py
│           ├── jira_client.py, qdrant_memory.py
│           └── llm_client.py
│
├── agents/                  # agena-agents
│   └── src/agena_agents/
│       ├── agents/          # AI agent orchestration
│       │   ├── orchestrator.py    # AgentOrchestrator (main coordinator)
│       │   ├── crewai_agents.py   # CrewAI agent runners (8 roles)
│       │   ├── langgraph_flow.py  # LangGraph state graph (5 nodes)
│       │   └── prompts.py         # Default prompt templates
│       └── memory/          # Vector memory abstraction
│           ├── base.py      # Abstract memory interface
│           └── qdrant.py    # Qdrant implementation
│
├── api/                     # agena-api
│   └── src/agena_api/
│       └── api/
│           ├── main.py            # FastAPI app bootstrap
│           ├── dependencies.py    # Auth, tenant, RBAC injection
│           ├── middleware/        # Rate limit, logging, tenant
│           └── routes/            # 18 route modules
│               ├── agents.py, tasks.py, flows.py
│               ├── auth.py, org.py, billing.py
│               ├── analytics.py, github.py, integrations.py
│               ├── preferences.py, notifications.py
│               └── ... (memory, refinement, usage, webhooks, ws)
│
└── worker/                  # agena-worker
    └── src/agena_worker/
        └── workers/
            └── redis_worker.py    # Redis queue consumer + task executor
```

**Other root-level directories:**

```
alembic/         # Database migrations (24 versions)
db/init.sql      # MySQL bootstrap script
docker/          # Dockerfiles + SSL certificate
docs/            # Architecture Decision Records
frontend/        # Next.js 14 app (React 18, TypeScript)
mobile/          # Mobile app
scripts/         # Utility scripts (import rewriter, locale translator)
tests/           # Test suite
```

### Package Dependency Graph

```
agena-core       ← no internal deps (foundation)
agena-models     ← depends on agena-core
agena-services   ← depends on agena-core, agena-models
agena-agents     ← depends on agena-core, agena-models, agena-services
agena-api        ← depends on all above
agena-worker     ← depends on agena-core, agena-models, agena-services
```

### Install a Single Package

```bash
pip install -e packages/core
pip install -e packages/models
pip install -e packages/agents   # includes CrewAI + LangGraph
```

---

## Tech Stack

| Layer | Technology |
|---|---|
| **Backend** | Python 3.11, FastAPI, SQLAlchemy 2.0 (async), Pydantic v2 |
| **AI** | CrewAI, LangGraph, OpenAI SDK (GPT-5, Gemini fallback) |
| **Database** | MySQL 8.0, Alembic migrations |
| **Queue** | Redis 7 |
| **Vector Memory** | Qdrant (optional, `QDRANT_ENABLED=true`) |
| **Frontend** | Next.js 14, React 18, TypeScript |
| **Auth** | JWT (python-jose), bcrypt, RBAC (4 roles) |
| **Deployment** | Docker Compose, Nginx (blue/green frontend) |

---

## CLI

`@agenaai/cli` drives the whole platform from the terminal — auth,
tasks, skills, refinement, runtimes, and the host bridge daemon:

```bash
# Homebrew (macOS / Linux) — recommended
brew install aozyildirim/tap/agena

# npm (any platform)
npm install -g @agenaai/cli
```

```bash
# Auth + tenant
agena setup                    # device-code OAuth → saves config → starts daemon
agena login                    # login only
agena whoami                   # current user + tenant + JWT source
agena org list / org switch <slug>

# Local CLI bridge (Claude / Codex)
agena daemon start|stop|status|logs
agena runtime list|status <id>

# Tasks
agena task list [-s running|queued|...]
agena task show <id>
agena task logs <id>
agena task create -t "Fix login bug" --assign

# Team skill catalog
agena skill list [-q <query>] [-t <pattern_type>]
agena skill show <id>
agena skill search "nullable pointer panic"    # vector search
agena skill delete <id> -y

# Sprint refinement (Qdrant-grounded SP estimates)
agena refinement backfill -p MyProject -t MyTeam --days 730
agena refinement backfill-status
agena refinement history [--sp 5] [-q auth]
agena refinement analyze -p MyProject -t MyTeam --sprint-path '...'
```

- **Device-code OAuth** — no JWT copy-paste; browser opens, you
  confirm a 6-digit code.
- **Keychain credential storage** — JWT held in macOS Keychain /
  libsecret / Windows Credential Manager when available.
- **Bundled bridge** — `agena daemon start` ships with its own copy
  of `bridge-server.mjs`, so `npm install -g @agenaai/cli` is
  self-contained.
- **Homebrew tap** — `aozyildirim/tap/agena` auto-updates via
  GoReleaser on every CLI release.

See [`packages/cli/README.md`](packages/cli/README.md) for the full
command reference.

---

## Quick Start

### 1. Clone and configure

```bash
git clone https://github.com/aozyildirim/Agena.git
cd Agena
cp .env.example .env
cp frontend/.env.example frontend/.env.local
```

### 2. Set required environment variables in `.env`

The only hard requirement is the JWT signing secret — everything else
(LLM provider, GitHub / Azure DevOps / Jira credentials) is configured
per-organization through the dashboard at `/dashboard/integrations`
once the stack is running, so the same deployment can serve teams that
use OpenAI alongside teams that use Claude CLI.

```env
JWT_SECRET_KEY=your-secret-key
# Optional — only set if you want a global default LLM key. Most users
# leave these empty and configure providers per-org from the UI.
# OPENAI_API_KEY=sk-...
# GEMINI_API_KEY=...
```

### 3. Start all services

```bash
./start.sh
```

This starts Docker services (backend, worker, frontend, MySQL, Redis, Qdrant) and the **CLI bridge on the host** for Claude/Codex CLI authentication via system keychain.

> **Note:** Use `start.sh` instead of `docker-compose up`. The CLI bridge must run on the host (not in Docker) to access Claude/Codex CLI auth. `./stop.sh` stops everything.

### 4. Access

| Service | URL |
|---|---|
| Frontend (dev) | http://localhost:3010 |
| Frontend Blue (prod) | http://localhost:3011 |
| Backend API | http://localhost:8010 |
| API Docs (Swagger) | http://localhost:8010/docs |
| CLI Bridge | http://localhost:9876/health |
| Qdrant Dashboard | http://localhost:6333/dashboard |

### 5. Create your first user

```bash
curl -X POST http://localhost:8010/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "full_name": "Admin User",
    "password": "Secret123!",
    "organization_name": "My Team"
  }'
```

### 6. Create platform admin (optional)

```bash
# Create admin (interactive — prompts for email, name, password)
docker exec -it ai_agent_api agena admin:user:create

# List all platform admins
docker exec ai_agent_api agena admin:user:list

# Promote existing user to admin
docker exec -it ai_agent_api agena admin:user:promote
```

Password requirements: 12+ characters, uppercase, lowercase, digit, and special character.

The admin panel is accessible at `/dashboard/admin` after login. Only platform admins can see it.

---

## Environment Variables

All configuration is via environment variables. See `.env.example` for the full list. Key ones:

| Variable | Description | Required |
|---|---|---|
| `JWT_SECRET_KEY` | JWT signing secret | Yes |
| `OPENAI_API_KEY` | OpenAI API key — global default if set | No (per-org override available in UI) |
| `GEMINI_API_KEY` | Google Gemini API key — global default if set | No (per-org override available in UI) |
| `MYSQL_HOST` | MySQL host | Default: `mysql` |
| `MYSQL_DATABASE` | Database name | Default: `ai_agent_db` |

GitHub, Azure DevOps, Jira, New Relic and Sentry credentials are **not
read from environment variables**. They live in `integration_configs`
and are managed per-organization from `/dashboard/integrations` so each
team can connect its own accounts. A single Agena deployment can host
many orgs without rebuilding the container.

---

## Docker Services

| Service | Container | Port | Description |
|---|---|---|---|
| `backend` | ai_agent_api | 8010 | FastAPI + auto-reload |
| `worker` | ai_agent_worker | — | Redis queue consumer |
| `cli-bridge` | (host process) | 9876 | Claude/Codex CLI bridge (runs on host, not Docker) |
| `frontend` | ai_agent_frontend | 3010 | Next.js (dev) |
| `frontend_blue` | ai_agent_frontend_blue | 3011 | Next.js (blue, prod) |
| `frontend_green` | ai_agent_frontend_green | 3012 | Next.js (green, prod) |
| `mysql` | ai_agent_mysql | 3307 | MySQL 8.0 |
| `redis` | ai_agent_redis | 6380 | Redis 7 |
| `qdrant` | ai_agent_qdrant | 6333 | Qdrant vector DB |

### CLI Bridge

The CLI bridge runs **on the host** (not in Docker) so it can access Claude/Codex CLI authentication (macOS Keychain, browser OAuth). `start.sh` handles this automatically.

```bash
# Manual start (if not using start.sh):
node docker/bridge-server.mjs &

# Check status:
curl http://localhost:9876/health
# → {"status":"ok","codex":true,"claude":true,"codex_auth":true,"claude_auth":true}
```

Docker containers reach the bridge via `http://host.docker.internal:9876`.

### Common Commands

```bash
# Start everything (recommended)
./start.sh

# Restart backend after code changes (hot-reload via volume mount)
docker-compose restart backend

# Restart worker (no hot-reload, needs restart)
docker-compose restart worker

# Rebuild a specific service
docker-compose up -d --build backend

# View logs
docker logs -f ai_agent_api
docker logs -f ai_agent_worker

# Shell into backend container
docker-compose exec backend bash
```

---

## Local Development

### Backend (without Docker)

```bash
python3.11 -m venv .venv
source .venv/bin/activate

# Install all packages in editable mode
pip install -r requirements.txt
pip install -e packages/core \
    -e packages/models \
    -e packages/services \
    -e packages/agents \
    -e packages/api \
    -e packages/worker

# Run API
uvicorn agena_api.api.main:app --reload --host 0.0.0.0 --port 8010

# Run Worker (separate terminal)
python -m agena_worker.workers.redis_worker
```

### Frontend

```bash
cd frontend
npm install
npm run dev        # Development (http://localhost:3010)
npm run build      # Production build
npm run lint       # Lint check
```

---

## Database Migrations

```bash
# Apply all pending migrations
docker-compose exec backend alembic upgrade head

# Create a new migration
docker-compose exec backend alembic revision -m "description"

# Check current version
docker-compose exec backend alembic current

# Rollback one step
docker-compose exec backend alembic downgrade -1
```

---

## Frontend Deploy (Zero-Downtime)

Frontend runs as blue/green production containers. Code is NOT volume-mounted.

```bash
# Zero-downtime deploy (rebuilds one container at a time):
./scripts/deploy-frontend.sh

# NEVER use docker-compose up --build for both at once — causes 502
```

For backend changes, hot-reload works via volume mount:
```bash
docker-compose restart backend worker
```

---

## API Endpoints

### Auth
| Method | Path | Description |
|---|---|---|
| POST | `/auth/signup` | Register + create org |
| POST | `/auth/login` | Get JWT token |

### Tasks
| Method | Path | Description |
|---|---|---|
| POST | `/tasks` | Create task |
| GET | `/tasks` | List tasks |
| GET | `/tasks/{id}` | Task detail |
| POST | `/tasks/{id}/assign` | Assign to AI agent |
| POST | `/tasks/{id}/cancel` | Cancel running task |
| GET | `/tasks/{id}/logs` | Execution logs |
| POST | `/tasks/import/azure` | Import from Azure DevOps |
| POST | `/tasks/import/jira` | Import from Jira |
| POST | `/tasks/import/newrelic` | Import from New Relic |
| POST | `/tasks/import/sentry` | Import from Sentry |
| POST | `/tasks/{id}/sentry-resolve` | Resolve/unresolve linked Sentry issue |
| POST | `/webhooks/pr-merged` | PR merge webhook (auto-resolves Sentry) |

### Agents & Flows
| Method | Path | Description |
|---|---|---|
| POST | `/agents/run` | Run agent on task |
| GET | `/agents/live` | Live agent status |
| POST | `/flows/run` | Execute automation flow |
| GET | `/flows/templates` | List flow templates |

### Organization
| Method | Path | Description |
|---|---|---|
| POST | `/org/invite` | Send invite |
| POST | `/org/invite/accept` | Accept invite |
| GET | `/org/members` | List members |
| PUT | `/org/members/{id}/role` | Change role |

### Integrations
| Method | Path | Description |
|---|---|---|
| PUT | `/integrations/azure` | Configure Azure DevOps |
| PUT | `/integrations/jira` | Configure Jira |
| PUT | `/integrations/github` | Configure GitHub |
| GET | `/integrations` | List all configs |

### Analytics & DORA
| Method | Path | Description |
|---|---|---|
| GET | `/analytics/dora` | DORA metrics |
| GET | `/analytics/team-health` | Team health symptoms |
| GET | `/analytics/sprint` | Sprint analytics |

### Other
| Method | Path | Description |
|---|---|---|
| GET | `/preferences` | User preferences |
| PUT | `/preferences/prompts` | Prompt overrides |
| GET | `/billing/status` | Billing status |
| POST | `/billing/stripe/checkout` | Stripe checkout |
| GET | `/health` | Health check |

Full OpenAPI docs available at `/docs` when running.

---

## AI Pipeline

### How a Task Runs

1. **Task Created** — User creates task via UI or imports from Jira/Azure
2. **Queued** — Task goes to Redis queue with repo lock (prevents concurrent edits)
3. **fetch_context** — Vector memory retrieves similar past tasks for context
4. **analyze (PM Agent)** — Analyzes requirements, estimates story points, plans file changes
5. **generate_code (Developer Agent)** — Generates code patches following the plan
6. **review_code (Reviewer Agent)** — Reviews patches for correctness, security, patterns
7. **finalize** — Cleans output, creates branch, commits, opens PR
8. **Done** — Task marked complete, notifications sent, usage tracked

### Agent Roles

| Agent | Model | Purpose |
|---|---|---|
| Context Analyst | Small (fast) | Summarize memory + repo context |
| Product Manager | Large + reasoning | Technical analysis, scope, estimation |
| AI Planner | Large + reasoning | File-level change plan |
| Developer | Large (128K output) | Code patch generation |
| Reviewer | Large + reasoning | Code review + correction |
| Finalizer | Small | Clean output for git commit |

### Prompt Studio

System prompts are stored in the database and editable at runtime via the Prompt Studio UI. Changes take effect immediately without code deployment.

---

## Screenshots

### Boss Mode — Pixel Office
Manage your AI team in a retro pixel-art office. Each agent is a character you can click, assign tasks, and monitor in real time.

![Boss Mode](https://raw.githubusercontent.com/aozyildirim/Agena/main/frontend/public/readmeimg/boss.png)

### Agent Management
Configure AI agents with different roles. View performance analytics — flow coverage, activity share, latency, and success index per agent.

![Agent Management](https://raw.githubusercontent.com/aozyildirim/Agena/main/frontend/public/readmeimg/agentmanage.png)

### Create Agent
Three-step wizard: pick a pixel character and name, choose provider (OpenAI, Gemini, Codex CLI, Claude CLI, Custom), then select a model.

| Step 1 — Character | Step 2 — Provider | Step 3 — Model |
|---|---|---|
| ![Pick Character](https://raw.githubusercontent.com/aozyildirim/Agena/main/frontend/public/readmeimg/bossagentadd1.png) | ![Select Type](https://raw.githubusercontent.com/aozyildirim/Agena/main/frontend/public/readmeimg/bossagentadd4.png) | ![Choose Model](https://raw.githubusercontent.com/aozyildirim/Agena/main/frontend/public/readmeimg/bossagentadd2.png) |

### Agent Flows — Visual Pipeline Builder
Drag-and-drop flow editor with nodes for PM Analysis, Technical Plan, Development, and QA Test. Includes approval gates, run history, version control, and flow templates.

![Agent Flows](https://raw.githubusercontent.com/aozyildirim/Agena/main/frontend/public/readmeimg/flow.png)

### Sprint Board
Kanban-style board with color-coded columns. Import tasks directly from Azure DevOps or Jira sprints.

![Sprint Board](https://raw.githubusercontent.com/aozyildirim/Agena/main/frontend/public/readmeimg/Sprintboard.png)

### Sprint Performance
Team health dashboard with circular gauge score, timeline progress, completion tracking, and per-member expandable cards.

![Sprint Performance](https://raw.githubusercontent.com/aozyildirim/Agena/main/frontend/public/readmeimg/sprintperformance.png)

### Task Feed
Create tasks with title, description, story context, acceptance criteria, edge cases, and cost guardrails.

![Task Feed](https://raw.githubusercontent.com/aozyildirim/Agena/main/frontend/public/readmeimg/new_task.png)

### Repo Mappings
Map Azure DevOps repositories to local paths for code generation.

![Repo Mappings](https://raw.githubusercontent.com/aozyildirim/Agena/main/frontend/public/readmeimg/repomapp.png)

---

## Plans

| Plan | Tasks/Month | Features |
|---|---|---|
| **Free** | 5 | Basic pipeline, 1 integration |
| **Pro** | Unlimited | All features, priority queue |
| **Enterprise** | Unlimited | Custom models, SSO, dedicated support |

---

## Why AGENA?

| Challenge | How AGENA Solves It |
|---|---|
| Repetitive coding tasks eat developer hours | AI agents autonomously generate code from task descriptions |
| Code review bottlenecks slow delivery | Built-in AI reviewer catches issues before human review |
| Context switching kills productivity | Queue tasks, get PRs — AI handles the implementation |
| Copilot only suggests, you still code | AGENA delivers complete pull requests, not snippets |
| No visibility into AI work | Pixel agent dashboard shows real-time agent activity |

### AGENA vs GitHub Copilot

- **Copilot** = AI-assisted coding (you drive, AI suggests line by line)
- **AGENA** = Agentic AI coding (AI drives the full task-to-PR pipeline)

They're complementary: use Copilot for creative work, AGENA for well-defined tasks. Read more: [AGENA vs GitHub Copilot](https://agena.dev/blog/github-copilot-alternative)

### Learn More

- [What is Agentic AI?](https://agena.dev/blog/what-is-agentic-ai)
- [Agentic AI Nedir?](https://agena.dev/blog/agentic-ai-nedir)
- [AI Code Generation Best Practices](https://agena.dev/blog/ai-code-generation-best-practices)
- [Pixel Agent Technology](https://agena.dev/blog/pixel-agent-technology)
- [Use Cases](https://agena.dev/use-cases)
- [Documentation](https://agena.dev/docs)

---

## Contributing

This repository is open-source under the MIT License.

- License: [LICENSE](./LICENSE)
- Contributing: [CONTRIBUTING.md](./CONTRIBUTING.md)
- Code of Conduct: [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
- Security: [SECURITY.md](./SECURITY.md)

---

## Sponsor

The Sponsor card at the top of this README is the canonical entry point.
Direct link: [github.com/sponsors/aozyildirim](https://github.com/sponsors/aozyildirim)

Agena

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README