AGX｜本地 AI 编码代理工作台

access：来源确认 · npm install -g @mndrk/agx && agx init

project_type：来源确认 · AGX runs the **ticket → implementation → PR → review** loop. Tickets from Jira or Linear come in, agents draft the work, humans approve at every gate, and PRs go out.

<p align="center">
  <br>
  <img src="agx_icon.png" width="128" alt="AGX Icon">
</p>

<h3 align="center">Use agents for real work. Stay in control.</h3>

<p align="center">
  Getting agents to do things isn't the hard part anymore. Keeping track of everything they do —<br>
  without losing context, missing changes, or creating messes you can't untangle — is.<br>
  AGX is how I use agents seriously. Works with Claude, Codex, Gemini, and Ollama.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@mndrk/agx"><img src="https://img.shields.io/npm/dm/@mndrk/agx?color=blue&style=flat-square" alt="NPM Downloads"></a>
  <a href="https://www.npmjs.com/package/@mndrk/agx"><img src="https://img.shields.io/npm/v/@mndrk/agx?color=orange&style=flat-square" alt="NPM Version"></a>
  <a href="https://github.com/ramarlina/agx/stargazers"><img src="https://img.shields.io/github/stars/ramarlina/agx?color=blue&style=flat-square" alt="GitHub Stars"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License"></a>
</p>

```bash
npm install -g @mndrk/agx && agx init
```

<p align="center">
  AGX is a local workspace for running coding agents across your tickets, repos, and PRs — you stay the author.
</p>

<!-- 🎬 Terminal demo — drop a GIF or mp4 here showing: agx new → agent runs → checkpoint → resume -->
<p align="center">
  <a href="https://github.com/ramarlina/agx">
    <img src="agx-chat-to-tasks.gif" alt="AGX — chat with agents, work through tickets, approve before they act" width="100%">
  </a>
</p>

<p align="center">
  <a href="https://runagx.com">Website</a> •
  <a href="https://runagx.com/blog">Blog</a> •
  <a href="#get-agx">Install</a> •
  <a href="#what-you-get">Features</a> •
  <a href="#how-it-works">How It Works</a> •
  <a href="#cli-quick-reference">CLI</a>
</p>

---

## Why I built this

Hi, I'm Mendrika.

I built AGX because I kept wanting to use agents for more and more real work. Feature builds. Bug fixes. Research. Follow-up tasks. The problem was never getting them to do things. The problem was keeping track of everything without getting lost.

That started to feel like the real bottleneck. The better the agents got, the more parallel work I wanted to run. And the more parallel work I ran, the easier it was to lose context, miss changes, and create messes I couldn't reliably untangle.

AGX is my attempt to solve that. It's an exploration of what it would take to use agents seriously, while still staying in control.

Ships as a CLI, a local web dashboard, and a macOS desktop app — all from one repo.

### What staying in control looks like

| | Ad-hoc agent usage | AGX |
|---|---|---|
| **Tickets** | Live in Jira/Linear, separate from the agent | Ticket, code, PR, and review in one window |
| **Parallel work** | Tabs, scrollback, mental bookkeeping | Every ticket has a home; see what's moving at a glance |
| **Picking up where you left off** | Re-explain everything from scratch | Instant — the ticket remembers |
| **Human gates** | Whatever you remember to check | Built-in approve/reject before anything irreversible |
| **PR review** | Read the diff cold, guess at intent | First pass from a reviewer agent — you review what actually needs your judgment |
| **Provider lock-in** | One provider per session | Switch Claude ↔ Codex ↔ Gemini ↔ Ollama freely |
| **Observability** | Terminal scrollback | Dashboard, live presence, activity log |

---

## Quickstart (2 minutes)

```bash
npm install -g @mndrk/agx
cd my-project
agx init                   # Picks up your API keys automatically
agx board start            # Open the ticket → agent → PR board
```

## Get AGX

### npm (recommended)

```bash
npm install -g @mndrk/agx
cd my-project
agx init                   # First-time setup — picks up your API keys
agx board start            # Open the local dashboard
```

### Desktop App (macOS)

Download from [Releases](https://github.com/ramarlina/agx/releases). Bundles the UI, CLI, and Node runtime — install and go.

<details>
<summary>Build from source</summary>

```bash
git clone https://github.com/ramarlina/agx.git
cd agx && npm install
npm run local:dev          # Run the dashboard in dev mode
```

</details>

---

## What You Get

- **Ticket → agent → PR loop** — Point an agent at a Jira or Linear ticket, review the draft, ship the PR. Your tickets, repos, and PRs live in one window.
- **Human-in-the-loop at every gate** — Agents pause for your explicit approve/reject before anything irreversible. PR review starts with a first-pass from a reviewer agent so you spend judgment where it matters.
- **Chat with any provider** — Claude, Codex, Gemini, Ollama. Switch freely mid-thread.
- **A home for every ticket** — Objectives, scheduled jobs, chat threads, and terminal sessions all live under their project. Nothing is free-floating.
- **Agent teams** — Group agents by role (engineering, research, ops). Work routes automatically by tag.
- **Survives restarts** — Close your laptop, pick it up tomorrow. State is checkpointed, not rebuilt from conversation history.
- **Live presence** — See which agents are active on which projects and tickets in real time.
- **Fully local** — Runs on your machine. Your code never leaves. Full activity log, signed actions, destructive-command safeguards.

---

## How It Works

AGX runs the **ticket → implementation → PR → review** loop. Tickets from Jira or Linear come in, agents draft the work, humans approve at every gate, and PRs go out.

Under the hood, work is checkpointed at every step — so closing your laptop, restarting the machine, or coming back tomorrow all pick up exactly where you left off. Resuming is constant-cost: a thread that's been running for a week resumes as fast as one that started a minute ago.

### Architecture

- **State layer** — SQLite (WAL mode), durable checkpoints
- **CLI + daemon** — Provider tool calls, filesystem edits, worktree isolation
- **Decision layer** — Human gate transitions, review flow

Everything runs locally. Your code never leaves your machine.

---

## CLI Quick Reference

```bash
agx init                         # First-time setup
agx board start                  # Open the ticket → agent → PR board
agx claude -p "..."              # Chat with Claude (or codex / gemini / ollama)
```

| Provider | Alias | Command |
|----------|-------|---------|
| Claude | `c` | `agx claude -p "..."` |
| Codex | `x` | `agx codex -p "..."` |
| Gemini | `g` | `agx gemini -p "..."` |
| Ollama | `o` | `agx ollama -p "..."` |

<details>
<summary>Full CLI reference</summary>

### Projects & Repos

```bash
agx project list                           # List projects
agx repo add . --project my-project        # Analyze current repo and attach it
agx repo add ../service --project my-project --name API
agx workspace list --project my-project    # Show workspace map entries by category
agx workspace add repos backend /code/api --project my-project
agx workspace remove repos backend --project my-project
```

### Environment Variables

```bash
agx vars set API_URL https://example.com    # Set a variable
agx vars get API_URL                        # Get a variable
agx vars list                               # List all variables
```

### Setup

```bash
agx init                       # First-time setup wizard
agx config                     # Reconfigure providers, models, backend URL
```

</details>

---

## Prerequisites

- **Node.js** >= 22.16.0 (CLI install only; desktop app bundles its own runtime)
- **At least one AI provider CLI:**
  [Claude Code](https://claude.com/claude-code) ·
  [Codex CLI](https://www.npmjs.com/package/@openai/codex) ·
  [Gemini CLI](https://ai.google.dev/gemini-api/docs/cli) ·
  [Ollama](https://ollama.ai/)

No external database required. AGX uses SQLite locally.

---

<details>
<summary><strong>Development</strong></summary>

This repo is an npm workspace. CLI, dashboard, and desktop app all live here — clone once, run everything.

```text
agx/
  apps/
    local/          # Next.js dashboard (project home, chat, terminal, teams, objectives, tasks)
    desktop/        # Electron macOS app (bundles dashboard, CLI, and Node runtime)
  lib/              # CLI and runtime source
  commands/         # CLI command implementations
  cloud-runtime/    # Packaged standalone dashboard bundled into the npm artifact
```

### Run the dashboard

```bash
npm install
npm run local:dev        # Start the dashboard at localhost
```

### Build the dashboard

```bash
npm run local:build      # Production build
npm run board:bundle     # Package standalone runtime for the CLI
```

### Desktop app

```bash
cd apps/desktop
npm run dev              # Launch Electron in dev mode
npm run build:mac        # Build the macOS .app + .dmg
```

### Tech stack

* **Dashboard/Chat:** Next.js, Tailwind CSS
* **Desktop:** Electron, electron-builder
* **Database:** SQLite (WAL mode)
* **Runtime:** Node.js (TypeScript / `tsx`)
* **Streaming:** EventSource (CLI → board)

</details>

<details>
<summary><strong>Contributing</strong></summary>

Contributions welcome.

* **Ideas & questions:** GitHub Discussions
* **Bugs & features:** GitHub Issues
* **PRs:** Fork `main`, add tests, submit

</details>

<details>
<summary><strong>Telemetry</strong></summary>

**Telemetry is enabled by default.**

AGX collects anonymous usage data to improve the tool. Here's exactly what we collect:

| Data | Example |
|------|---------|
| OS & architecture | `darwin`, `arm64` |
| Node.js version | `v22.16.0` |
| AGX version | `1.4.55` |
| Commands run | `new`, `daemon start` |
| Provider used | `claude`, `codex`, `gemini`, `ollama` |
| Task outcomes | `completed`, `failed` |
| Timing | `duration_ms: 12345` |

**We do NOT collect:** prompts, code, API keys, file paths, or any PII.

### Disable telemetry

```bash
agx telemetry off
# or: export AGX_TELEMETRY=0
# or: ~/.agx/config.json → { "telemetry": { "enabled": false } }
```

</details>

---

## License

MIT

---

<p align="center">
  <strong>Direct the work. Let agents handle the busywork. Stay the author.</strong><br><br>
  <a href="https://github.com/ramarlina/agx/stargazers">⭐ Star this repo</a> if AGX saves you time · <a href="https://github.com/ramarlina/agx/issues">Report a bug</a> · <a href="https://runagx.com">runagx.com</a>
</p>

Node.js >= 22.16.0（仅 CLI）；至少一个供应商 CLI：Claude Code、Codex CLI、Gemini CLI 或 Ollama；需自备相应供应商的 API Key 或本地模型；AGX 自身费用与 runagx.com 服务是否收费待核验；Jira/Linear 集成所需授权范围待核验；遥测默认开启，可关闭。