https://github.com/ramarlina/agx
https://github.com/ramarlina/agx
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/ramarlina/agx
- Owner: ramarlina
- Created: 2026-02-02T19:46:31.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-03T05:02:43.000Z (about 2 months ago)
- Last Synced: 2026-04-03T12:33:05.508Z (about 2 months ago)
- Language: JavaScript
- Homepage: https://www.runagx.com
- Size: 25.4 MB
- Stars: 11
- Watchers: 0
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-cli-coding-agents - agx - based execution engine for AI coding agents; durable Wake→Work→Sleep loops that resume instantly across sessions. Supports Claude Code, Codex CLI, Gemini CLI, and Ollama. CLI + web dashboard + macOS app. (Harnesses & orchestration / Orchestrators & autonomous loops)
README
Use agents for real work. Stay in control.
Getting agents to do things isn't the hard part anymore. Keeping track of everything they do —
without losing context, missing changes, or creating messes you can't untangle — is.
AGX is how I use agents seriously. Works with Claude, Codex, Gemini, and Ollama.
```bash
npm install -g @mndrk/agx && agx init
```
Website •
Blog •
Install •
Features •
How It Works •
CLI
---
## 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.
> **Dogfooded hard:** 133 PRs and 500+ commits merged by AGX agents building AGX itself. [Read more →](https://runagx.com/blog)
### What staying in control looks like
| | Ad-hoc agent usage | AGX |
|---|---|---|
| **Parallel work** | Tabs, scrollback, mental bookkeeping | Every task has a home; see what's running at a glance |
| **Resuming a task** | Re-explain everything from scratch | Instant — loads last checkpoint, constant cost |
| **Multi-session tasks** | Manual context stitching | Wake / work / sleep loop, picks up where it left off |
| **Crash recovery** | Lost work | Checkpointed state survives restarts |
| **Human gates** | Whatever you remember to check | Built-in approve/reject before anything irreversible |
| **Provider lock-in** | One provider per session | Switch Claude ↔ Codex ↔ Gemini ↔ Ollama freely |
| **Observability** | Terminal scrollback | Dashboard, live presence, execution logs |
---
## Quickstart (2 minutes)
```bash
npm install -g @mndrk/agx
cd my-project
agx init # Picks up your API keys automatically
agx new "Add rate limiting to the API" # Create your first task
agx run 1 # Watch the agent work
# ...close your laptop, come back tomorrow...
agx run 1 # Resumes instantly from the last checkpoint
```
## 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.
Build from source
```bash
git clone https://github.com/ramarlina/agx.git
cd agx && npm install
npm run local:dev # Run the dashboard in dev mode
```
---
## What You Get
- **A home for every task** — Objectives, scheduled jobs, chat threads, and terminal sessions all live under their project. Nothing is free-floating.
- **Chat with any provider** — Claude, Codex, Gemini, Ollama. Switch freely mid-task.
- **Durable tasks** — Survive restarts, crashes, and reboots. State is checkpointed, not rebuilt from conversation history.
- **Human-in-the-loop** — Agents pause at gates for your explicit approve/reject before touching anything dangerous.
- **Agent teams** — Group agents by role (engineering, research, ops). Tasks route automatically by tag.
- **Live presence** — See which agents are active on which projects and tasks in real time.
- **Fully local** — Runs on your machine. Your code never leaves. Full execution logs, task signing, destructive-command safeguards.
---
## How It Works
AGX treats agent memory as **durable state**, not conversation history.
Each task runs in a **Wake - Work - Sleep** loop:
1. **Wake** — Load full context from the last checkpoint
2. **Work** — Execute commands, edit files, validate output
3. **Sleep** — Save state and yield, ready to resume anytime
Resuming is constant-cost. A task that ran for a week resumes as fast as one that ran for a minute.
### Architecture
```
┌──────────────┐ ┌──────────────┐ ┌────────────┐
│ Dashboard │◄─►│ SQLite │◄─►│ Task Queue │
│ (Next.js) │ │ Durable State│ │ │
└──────────────┘ └──────────────┘ └────────────┘
┌──────────────┐ ┌──────────────┐ ┌────────────┐
│ AI Provider │◄─►│ AGX CLI │◄─►│ AGX Daemon │
│ C/Codex/G/O │ │ │ │ │
└──────────────┘ └──────────────┘ └────────────┘
```
- **State layer** — SQLite (WAL mode), durable checkpoints, task queueing
- **Execution layer** — CLI + daemon, provider tool calls, filesystem edits
- **Decision layer** — Execution graph runtime + human gate transitions
---
## CLI Quick Reference
```bash
agx new "build login page" # Create a task
agx run # Run it
agx status # Check progress
agx approve # Approve a human gate
```
| Provider | Alias | Command |
|----------|-------|---------|
| Claude | `c` | `agx claude -p "..."` |
| Codex | `x` | `agx codex -p "..."` |
| Gemini | `g` | `agx gemini -p "..."` |
| Ollama | `o` | `agx ollama -p "..."` |
| Flag | Purpose |
|------|---------|
| `-p` | Task goal / prompt |
| `-a` | Autonomous mode (create + run until done) |
| `-y` | Skip confirmations |
| `--swarm` | Multi-agent execution |
Full CLI reference
### Tasks
```bash
agx new "" # Create a new task
agx run # Run a specific task
agx status [task-id-or-slug] # Show status
agx retry [--from ] # Reset + retry
agx approve [--node ] [-m "feedback"] # Approve a gate
agx reject [--node ] [-m "feedback"] # Reject a gate
agx deps [--depends-on ... | --clear] # Manage dependencies
```
### 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
```
### 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
```
---
## Prerequisites
- **Node.js** >= 22.16.0 (CLI install only; desktop app bundles its own runtime)
- **At least one AI provider CLI:**
[Claude Code](https://docs.anthropic.com/claude/docs/claude-cli) ·
[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.
---
Development
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)
Contributing
Contributions welcome.
* **Ideas & questions:** GitHub Discussions
* **Bugs & features:** GitHub Issues
* **PRs:** Fork `main`, add tests, submit
Telemetry
**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 } }
```
---
## License
MIT
---
Stop re-explaining context. Let your agents remember.
⭐ Star this repo if AGX saves you time · Report a bug · runagx.com