{"id":46653785,"url":"https://github.com/ramarlina/agx","last_synced_at":"2026-04-17T10:11:20.545Z","repository":{"id":336102504,"uuid":"1148288640","full_name":"ramarlina/agx","owner":"ramarlina","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-03T05:02:43.000Z","size":26630,"stargazers_count":11,"open_issues_count":1,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T12:33:05.508Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.runagx.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ramarlina.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-02T19:46:31.000Z","updated_at":"2026-04-03T05:02:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ramarlina/agx","commit_stats":null,"previous_names":["ramarlina/agx"],"tags_count":94,"template":false,"template_full_name":null,"purl":"pkg:github/ramarlina/agx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramarlina%2Fagx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramarlina%2Fagx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramarlina%2Fagx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramarlina%2Fagx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ramarlina","download_url":"https://codeload.github.com/ramarlina/agx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramarlina%2Fagx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31542384,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"online","status_checked_at":"2026-04-08T02:00:06.127Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-08T07:03:50.284Z","updated_at":"2026-04-17T10:11:20.523Z","avatar_url":"https://github.com/ramarlina.png","language":"JavaScript","funding_links":[],"categories":["Parallel Agent Runners","Harnesses \u0026 orchestration"],"sub_categories":["Orchestrators \u0026 autonomous loops"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cbr\u003e\n  \u003cimg src=\"agx_icon.png\" width=\"128\" alt=\"AGX Icon\"\u003e\n\u003c/p\u003e\n\n\u003ch3 align=\"center\"\u003eUse agents for real work. Stay in control.\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  Getting agents to do things isn't the hard part anymore. Keeping track of everything they do —\u003cbr\u003e\n  without losing context, missing changes, or creating messes you can't untangle — is.\u003cbr\u003e\n  AGX is how I use agents seriously. Works with Claude, Codex, Gemini, and Ollama.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@mndrk/agx\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/@mndrk/agx?color=blue\u0026style=flat-square\" alt=\"NPM Downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@mndrk/agx\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@mndrk/agx?color=orange\u0026style=flat-square\" alt=\"NPM Version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/ramarlina/agx/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/ramarlina/agx?color=blue\u0026style=flat-square\" alt=\"GitHub Stars\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-green?style=flat-square\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/ramarlina/agx/pulls?q=is%3Apr+is%3Amerged\"\u003e\u003cimg src=\"https://img.shields.io/badge/PRs_merged_by_agents-167-blueviolet?style=flat-square\" alt=\"Agent PRs\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n```bash\nnpm install -g @mndrk/agx \u0026\u0026 agx init\n```\n\n\u003c!-- 🎬 Terminal demo — drop a GIF or mp4 here showing: agx new → agent runs → checkpoint → resume --\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/ramarlina/agx\"\u003e\n    \u003cimg src=\"agx-chat-to-tasks.gif\" alt=\"AGX — chat with agents, create tasks, approve before they act\" width=\"100%\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://runagx.com\"\u003eWebsite\u003c/a\u003e •\n  \u003ca href=\"https://runagx.com/blog\"\u003eBlog\u003c/a\u003e •\n  \u003ca href=\"#get-agx\"\u003eInstall\u003c/a\u003e •\n  \u003ca href=\"#what-you-get\"\u003eFeatures\u003c/a\u003e •\n  \u003ca href=\"#how-it-works\"\u003eHow It Works\u003c/a\u003e •\n  \u003ca href=\"#cli-quick-reference\"\u003eCLI\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Why I built this\n\nHi, I'm Mendrika.\n\nI 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.\n\nThat 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.\n\nAGX is my attempt to solve that. It's an exploration of what it would take to use agents seriously, while still staying in control.\n\nShips as a CLI, a local web dashboard, and a macOS desktop app — all from one repo.\n\n\u003e **Dogfooded hard:** 133 PRs and 500+ commits merged by AGX agents building AGX itself. [Read more →](https://runagx.com/blog)\n\n### What staying in control looks like\n\n| | Ad-hoc agent usage | AGX |\n|---|---|---|\n| **Parallel work** | Tabs, scrollback, mental bookkeeping | Every task has a home; see what's running at a glance |\n| **Resuming a task** | Re-explain everything from scratch | Instant — loads last checkpoint, constant cost |\n| **Multi-session tasks** | Manual context stitching | Wake / work / sleep loop, picks up where it left off |\n| **Crash recovery** | Lost work | Checkpointed state survives restarts |\n| **Human gates** | Whatever you remember to check | Built-in approve/reject before anything irreversible |\n| **Provider lock-in** | One provider per session | Switch Claude ↔ Codex ↔ Gemini ↔ Ollama freely |\n| **Observability** | Terminal scrollback | Dashboard, live presence, execution logs |\n\n---\n\n## Quickstart (2 minutes)\n\n```bash\nnpm install -g @mndrk/agx\ncd my-project\nagx init                   # Picks up your API keys automatically\nagx new \"Add rate limiting to the API\"   # Create your first task\nagx run 1                  # Watch the agent work\n# ...close your laptop, come back tomorrow...\nagx run 1                  # Resumes instantly from the last checkpoint\n```\n\n## Get AGX\n\n### npm (recommended)\n\n```bash\nnpm install -g @mndrk/agx\ncd my-project\nagx init                   # First-time setup — picks up your API keys\nagx board start            # Open the local dashboard\n```\n\n### Desktop App (macOS)\n\nDownload from [Releases](https://github.com/ramarlina/agx/releases). Bundles the UI, CLI, and Node runtime — install and go.\n\n\u003cdetails\u003e\n\u003csummary\u003eBuild from source\u003c/summary\u003e\n\n```bash\ngit clone https://github.com/ramarlina/agx.git\ncd agx \u0026\u0026 npm install\nnpm run local:dev          # Run the dashboard in dev mode\n```\n\n\u003c/details\u003e\n\n---\n\n## What You Get\n\n- **A home for every task** — Objectives, scheduled jobs, chat threads, and terminal sessions all live under their project. Nothing is free-floating.\n- **Chat with any provider** — Claude, Codex, Gemini, Ollama. Switch freely mid-task.\n- **Durable tasks** — Survive restarts, crashes, and reboots. State is checkpointed, not rebuilt from conversation history.\n- **Human-in-the-loop** — Agents pause at gates for your explicit approve/reject before touching anything dangerous.\n- **Agent teams** — Group agents by role (engineering, research, ops). Tasks route automatically by tag.\n- **Live presence** — See which agents are active on which projects and tasks in real time.\n- **Fully local** — Runs on your machine. Your code never leaves. Full execution logs, task signing, destructive-command safeguards.\n\n---\n\n## How It Works\n\nAGX treats agent memory as **durable state**, not conversation history.\n\nEach task runs in a **Wake - Work - Sleep** loop:\n\n1. **Wake** — Load full context from the last checkpoint\n2. **Work** — Execute commands, edit files, validate output\n3. **Sleep** — Save state and yield, ready to resume anytime\n\nResuming is constant-cost. A task that ran for a week resumes as fast as one that ran for a minute.\n\n### Architecture\n\n```\n┌──────────────┐   ┌──────────────┐   ┌────────────┐\n│ Dashboard    │◄─►│ SQLite       │◄─►│ Task Queue │\n│ (Next.js)    │   │ Durable State│   │            │\n└──────────────┘   └──────────────┘   └────────────┘\n\n┌──────────────┐   ┌──────────────┐   ┌────────────┐\n│ AI Provider  │◄─►│ AGX CLI      │◄─►│ AGX Daemon │\n│ C/Codex/G/O  │   │              │   │            │\n└──────────────┘   └──────────────┘   └────────────┘\n```\n\n- **State layer** — SQLite (WAL mode), durable checkpoints, task queueing\n- **Execution layer** — CLI + daemon, provider tool calls, filesystem edits\n- **Decision layer** — Execution graph runtime + human gate transitions\n\n---\n\n## CLI Quick Reference\n\n```bash\nagx new \"build login page\"       # Create a task\nagx run \u003cid\u003e                     # Run it\nagx status                       # Check progress\nagx approve \u003cid\u003e                 # Approve a human gate\n```\n\n| Provider | Alias | Command |\n|----------|-------|---------|\n| Claude | `c` | `agx claude -p \"...\"` |\n| Codex | `x` | `agx codex -p \"...\"` |\n| Gemini | `g` | `agx gemini -p \"...\"` |\n| Ollama | `o` | `agx ollama -p \"...\"` |\n\n| Flag | Purpose |\n|------|---------|\n| `-p` | Task goal / prompt |\n| `-a` | Autonomous mode (create + run until done) |\n| `-y` | Skip confirmations |\n| `--swarm` | Multi-agent execution |\n\n\u003cdetails\u003e\n\u003csummary\u003eFull CLI reference\u003c/summary\u003e\n\n### Tasks\n\n```bash\nagx new \"\u003cgoal\u003e\"                                 # Create a new task\nagx run \u003ctask_id\u003e                               # Run a specific task\nagx status [task-id-or-slug]                    # Show status\nagx retry \u003ctask_id-or-slug\u003e [--from \u003cstage\u003e]    # Reset + retry\nagx approve \u003ctask\u003e [--node \u003cnode-id\u003e] [-m \"feedback\"]  # Approve a gate\nagx reject \u003ctask\u003e [--node \u003cnode-id\u003e] [-m \"feedback\"]   # Reject a gate\nagx deps \u003ctask\u003e [--depends-on \u003ctask\u003e ... | --clear]    # Manage dependencies\n```\n\n### Projects \u0026 Repos\n\n```bash\nagx project list                           # List projects\nagx repo add . --project my-project        # Analyze current repo and attach it\nagx repo add ../service --project my-project --name API\n```\n\n### Environment Variables\n\n```bash\nagx vars set API_URL https://example.com    # Set a variable\nagx vars get API_URL                        # Get a variable\nagx vars list                               # List all variables\n```\n\n### Setup\n\n```bash\nagx init                       # First-time setup wizard\nagx config                     # Reconfigure providers, models, backend URL\n```\n\n\u003c/details\u003e\n\n---\n\n## Prerequisites\n\n- **Node.js** \u003e= 22.16.0 (CLI install only; desktop app bundles its own runtime)\n- **At least one AI provider CLI:**\n  [Claude Code](https://docs.anthropic.com/claude/docs/claude-cli) ·\n  [Codex CLI](https://www.npmjs.com/package/@openai/codex) ·\n  [Gemini CLI](https://ai.google.dev/gemini-api/docs/cli) ·\n  [Ollama](https://ollama.ai/)\n\nNo external database required. AGX uses SQLite locally.\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDevelopment\u003c/strong\u003e\u003c/summary\u003e\n\nThis repo is an npm workspace. CLI, dashboard, and desktop app all live here — clone once, run everything.\n\n```text\nagx/\n  apps/\n    local/          # Next.js dashboard (project home, chat, terminal, teams, objectives, tasks)\n    desktop/        # Electron macOS app (bundles dashboard, CLI, and Node runtime)\n  lib/              # CLI and runtime source\n  commands/         # CLI command implementations\n  cloud-runtime/    # Packaged standalone dashboard bundled into the npm artifact\n```\n\n### Run the dashboard\n\n```bash\nnpm install\nnpm run local:dev        # Start the dashboard at localhost\n```\n\n### Build the dashboard\n\n```bash\nnpm run local:build      # Production build\nnpm run board:bundle     # Package standalone runtime for the CLI\n```\n\n### Desktop app\n\n```bash\ncd apps/desktop\nnpm run dev              # Launch Electron in dev mode\nnpm run build:mac        # Build the macOS .app + .dmg\n```\n\n### Tech stack\n\n* **Dashboard/Chat:** Next.js, Tailwind CSS\n* **Desktop:** Electron, electron-builder\n* **Database:** SQLite (WAL mode)\n* **Runtime:** Node.js (TypeScript / `tsx`)\n* **Streaming:** EventSource (CLI → board)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eContributing\u003c/strong\u003e\u003c/summary\u003e\n\nContributions welcome.\n\n* **Ideas \u0026 questions:** GitHub Discussions\n* **Bugs \u0026 features:** GitHub Issues\n* **PRs:** Fork `main`, add tests, submit\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTelemetry\u003c/strong\u003e\u003c/summary\u003e\n\n**Telemetry is enabled by default.**\n\nAGX collects anonymous usage data to improve the tool. Here's exactly what we collect:\n\n| Data | Example |\n|------|---------|\n| OS \u0026 architecture | `darwin`, `arm64` |\n| Node.js version | `v22.16.0` |\n| AGX version | `1.4.55` |\n| Commands run | `new`, `daemon start` |\n| Provider used | `claude`, `codex`, `gemini`, `ollama` |\n| Task outcomes | `completed`, `failed` |\n| Timing | `duration_ms: 12345` |\n\n**We do NOT collect:** prompts, code, API keys, file paths, or any PII.\n\n### Disable telemetry\n\n```bash\nagx telemetry off\n# or: export AGX_TELEMETRY=0\n# or: ~/.agx/config.json → { \"telemetry\": { \"enabled\": false } }\n```\n\n\u003c/details\u003e\n\n---\n\n## License\n\nMIT\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eStop re-explaining context. Let your agents remember.\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\n  \u003ca href=\"https://github.com/ramarlina/agx/stargazers\"\u003e⭐ Star this repo\u003c/a\u003e if AGX saves you time · \u003ca href=\"https://github.com/ramarlina/agx/issues\"\u003eReport a bug\u003c/a\u003e · \u003ca href=\"https://runagx.com\"\u003erunagx.com\u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framarlina%2Fagx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Framarlina%2Fagx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framarlina%2Fagx/lists"}