Argus

A self-hosted, OS-agnostic agentic development environment. Argus is a local-first, single-user system where you build a roster of persistent coding agents and work alongside them — in a conversation pane or a terminal, per session. Every agent is a durable identity — its own name, photo, git repository, runtime CLI, and long-lived memory — not a throwaway chat session. You come back to the same agent tomorrow and it remembers what it learned today.

Fork notice: This repository (boostedchaos/ade) is a fork of per-simmons/damon-ade that adds Windows 11 x64 support, and additionally incorporates the client–server restructuring and quality-of-life improvements from CameronCrow/papyrus-ade (renamed back to ADE). It is not an official upstream release.

Beyond the desktop app, the codebase is restructured around one move: one server, any screen. A headless ade-server daemon runs where your repos and coding CLIs live; every device — Windows laptop, Mac, iPhone — is just a browser pointed at it.

┌───────────────── your devices ─────────────────┐
│  Windows laptop      Mac           iPhone      │
│    Chrome/Edge      Safari       Safari (PWA)  │
└─────────┬──────────────┬──────────────┬────────┘
          │   HTTPS + WSS · tRPC · token auth
          ▼
  ade-server  (Node daemon on one machine)
  ├─ agents, teams, sessions, files, settings
  ├─ agent core: repos/worktrees, persistent memory
  └─ terminal-host daemon (node-pty)
       └─ claude / codex / opencode CLIs

Status: The Electron desktop app (macOS + Windows 11 x64) is the primary, shipping form factor. The client–server components (ade-server + web UI) are functional and under active development; their design history lives in planning/.

Download (desktop app)

Windows 11 x64 users can download the installer or portable zip from the boostedchaos/ade releases. The Windows build is currently unsigned, so Windows SmartScreen will require More info → Run anyway.

macOS (Apple Silicon) users can download the DMG from the mac-v* releases on the same releases page. The mac build is unsigned. macOS quarantines it on download and, on Apple Silicon, reports "Argus is damaged and can't be opened." That wording is alarming and wrong — the file is not damaged, it is quarantined. Clear the quarantine flag:

xattr -dr com.apple.quarantine /Applications/Argus.app

Verify downloads against the release's SHA256SUMS.txt. Building from source sidesteps this entirely: Gatekeeper quarantine applies only to downloaded files, never to an app built on the Mac that runs it.

Release channels in this repo: windows-v* (Windows desktop), mac-v* (macOS desktop), v* (headless ade-server).

The product

The interface is a two-level left rail. Teams group your work; inside each team live Agents. Selecting an agent opens its workspace: a strip of session tabs, each running the agent's coding CLI inside that agent's own git worktree. A session tab is either an ACP conversation pane or a terminal — see Agent sessions below for which one you get. A model bar under the tabs lets you spawn a session on a different model without leaving the agent. On the right, the Agent Files panel shows the agent's memory growing as it works.

Argus runs whatever CLI coding agents you already have installed. Claude Code, OpenAI's Codex, and OpenCode are first-class runtimes. The model bar can also launch sessions on Kimi K2.7, MiniMax M3, and GLM 5.2 through a single OpenRouter key you enter once, in-app. Nothing here is a hosted service — your code, your keys, and your agents' memory all stay on your machine.

Terminal sessions live in a detached daemon, not in the app: they survive app restarts, browser disconnects, and (by design) a phone that locks its screen mid-session.

Mission Control (new in 0.4.0) gives the app a command line. The ade tool — already on the PATH of every terminal pane Argus opens — creates and splits panes, types into terminals and reads their screens, drives browser panes, and keeps per-workspace todos. Argus tracks each agent's state from its own hooks — working, waiting on you, idle — and a pane whose agent is blocked raises a ring and a badge you can jump straight to. There is also an experimental ade claude-teams launcher (macOS) that runs Claude Code's agent-teams feature with each teammate materialized as a real pane you can watch. See docs/mission-control.md and CHANGELOG.md.

Agent sessions: conversation or terminal

A session tab is one of two things. Since 0.5.0 the default for an eligible agent is an ACP conversation pane — a chat-style view driven by the Agent Client Protocol, with the agent running as its own supervised subprocess. Everything else is a terminal, exactly as before.

Eligibility for the ACP default is two conditions, both required:

1. the agent's runtime is Claude Code, and
2. the agent has a git worktree.

Anything else opens as a terminal, with no setting to change that:

• Non-Claude runtimes (Codex, OpenCode) are terminal sessions.
• The Kimi, MiniMax and GLM model-bar runtimes are terminal sessions too. They are the claude CLI pointed at OpenRouter by environment variables and a --model flag written into the terminal command string; the ACP path spawns the adapter instead of writing a command line, so flipping them would silently run Claude rather than the model you picked.
• An agent with no worktree is a terminal session. The pane requires a working directory, and a session opened in the wrong directory is worse than one that fails to open.

(Rule read from apps/desktop/src/renderer/stores/tabs/acp-flip.ts.)

Opting out

Two opt-outs, one per-session and one global.

• Per session: the tab-strip + menu lists ACP Session and Agent session (terminal). Picking a view by name overrides the global setting in either direction — but it still cannot conjure a worktree, so a worktree-less agent stays on the terminal path. (Labels from apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/GroupStrip/components/AddTabButton/AddTabButton.tsx.)
• Globally: Settings → Behavior (the panel renders under the heading Features) has Agent sessions open as, with the choices ACP conversation and Terminal. The app's own help text reads: "How a new Claude Code agent session opens. Other runtimes, and agents with no worktree, always open in a terminal." Setting it to Terminal restores the pre-0.5.0 behaviour everywhere. It is read per launch, so a change applies to the next session without restarting the app. (Labels from apps/desktop/src/renderer/routes/_authenticated/settings/behavior/components/BehaviorSettings/BehaviorSettings.tsx.)

What the conversation pane gives you

• A live control bar in the pane toolbar — model, effort, fast mode and agent — written mid-session and populated from the adapter's own reported options. Every write is followed by a mandatory read-back, because the adapter can accept an illegal value, reply success, and silently downgrade to default. The bar renders only read-back truth, warns when the applied value differs from the requested one, and says "could not verify" when the wire carried no options.
• A slash-command palette. Typing / at the start of the composer opens an autocomplete list fed by the adapter's available_commands_update — your real skills and commands. The palette distinguishes "commands not loaded yet" from "session ended — commands unavailable", so an empty list and a dead session never look alike.
• Permission modes. Settings → Behavior → ACP permission mode offers Auto-approve and Ask me. On Ask me, a real permission prompt arrives in the pane as an answerable card and rings Mission Control. The app's help text: "Whether an ACP agent session asks before running a tool that needs permission. Applies to new sessions — a session already running keeps the mode it started with." (Same BehaviorSettings.tsx file.)
• AskUserQuestion. The pane advertises form elicitation, so the agent can ask multiple-choice questions again; they render as cards.
• Resume and replay. A restored pane replays its whole conversation through session/load, including a session created by the plain claude CLI — so + reopens your newest conversation the way claude --resume did. The router buffers events so a replay cannot stream into a void, and dropped events are counted and shown rather than swallowed.
• A fresh-session fallback. An unknown or unloadable session id starts a clean session instead of failing. A New session button is present in every lifecycle of the pane; if the current pane holds a conversation it arms into Discard & restart? and takes a second click.

Terminal sessions are unchanged — including the detached daemon described above.

Prerequisites

Argus orchestrates coding CLIs; it does not bundle them. On the machine that runs the server you need:

• Git — required. Each agent gets its own repository or worktree.

• At least one agent CLI. Claude Code is recommended, because it also powers the Kimi, MiniMax, and GLM sessions from the model bar:

  npm i -g @anthropic-ai/claude-code
  npm i -g @openai/codex        # optional: OpenAI Codex sessions
  npm i -g opencode-ai          # optional: OpenCode runtime

  Claude Code is required for ACP panes specifically: Argus bundles the ACP adapter but not the CLI it drives, and points it at your installed claude.

• Node.js LTS — runs ade-server (and installs the CLIs above).

• An OpenRouter API key — only for the open-model sessions; entered once, in-app, encrypted at rest.

Build from source

Requires Bun 1.0+ (as package manager/tooling).

git clone https://github.com/boostedchaos/ade.git
cd ade
bun install

# Desktop app (current form factor, macOS):
cd apps/desktop
bun run compile:app        # builds main + preload + renderer into dist/
bunx electron .            # launches the built app

The headless server (apps/server) and browser UI (apps/webui) land in Phases 1–2 of the plan.

No-admin install (Windows)

Everything Argus itself needs installs per-user — no elevation. The catch is picking the right installer at each step; the machine-wide variants all want admin.

1. Git — use the per-user installer (or portable zip), then:

   git config --global core.longpaths true

   The longpaths flag is required: agent checkouts live under ~/.ade/agents/<uuid>/worktree/, and that prefix pushes deep repos past Windows' 260-char path limit. This git setting is enough — the system-wide registry toggle is not needed.

2. Node.js 24 (LTS) — install via fnm or extract the plain Node zip into a user directory. Avoid the Node MSI and nvm-windows: both need admin (nvm-windows symlinks into C:\Program Files).

3. Bun — the official installer is user-level (~/.bun):

   irm bun.sh/install.ps1 | iex

4. Dependencies — from the repo root:

   bun install --ignore-scripts

   Then install better-sqlite3's prebuilt binding manually (bun's --ignore-scripts skips it):

   cd (ls node_modules\.bun\better-sqlite3@*\node_modules\better-sqlite3).FullName
   npx prebuild-install

   node-pty ships its prebuilds inside the package — no step needed. Everything lands in the project; nothing touches system paths. (This holds because Windows prebuilds exist for both native modules on Node 24 — if one were ever missing, compiling from source would need VS Build Tools, which does want admin.)

5. Build and run — the server and daemon must run under Node, not bun:

   cd apps\webui;  bun run build          # ~2 min
   cd ..\server;   bun run scripts\build.ts
   node dist\server.cjs serve --port 7777

   Open http://localhost:7777 and enter the token from ~\.ade\token. Binding to loopback on an unprivileged port means no firewall prompt and no elevation; ConPTY is built into Windows 10 1809+. The claude CLI installs per-user too (npm i -g under your user-writable Node).

What still needs admin (both outside Argus): installing Tailscale for remote access (network driver), and approving the Windows Firewall prompt if you bind the server to a LAN address instead of loopback. Localhost-only Argus runs fully unelevated.

How memory works

Every Argus agent keeps a persistent, self-curated memory, adapted from the Hermes agent. The design is deliberately simple: plain markdown files the agent reads at the start of every session and writes back to as it learns. The files live outside the git worktree, so they survive branch and worktree churn and are never committed to your code.

• AGENT.md — a short identity and operating brief.
• USER.md — a profile of you: name, preferences, communication style, hard rules.
• MEMORY.md — the agent's own notes: conventions, tool quirks, lessons learned, plus an index into longer topic files.
• Skills — reusable, multi-step procedures the agent writes for itself, each a SKILL.md whose body loads only when relevant.

A write-back protocol travels with the memory (when to save, when to skip, consolidate over append), and a session-end reflection loop prompts the agent to update its memory before finishing. The same canonical files feed every runtime through thin, auto-generated bridge files, so you can switch an agent's runtime without losing its memory. See docs/memory.md for the full design.

Design

Argus is built on one idea: the iris. An open ring with a pupil is simultaneously the app mark and the per-agent status indicator — it replaces every status dot, avatar and badge in the app, so a glance at the rail tells you which agents are working, which are waiting on you, and which are idle.

The app ships two themes, Ink (dark, the default) and Daylight (light), and sets its type in IBM Plex Sans and Mono, bundled locally so it works offline. Motion is limited to four movements that report state and never decorate; prefers-reduced-motion collapses all of them.

The design record lives in docs/design/argus/ — a full brief plus a 2x screenshot of every screen. What was actually built against it, including the deliberate deviations and what was left undone, is in docs/specs/argus-rebrand/BUILD-REPORT.md.

Remote access

The blessed path is Tailscale: tailscale serve in front of the server port gives TLS and tailnet-only access while the server stays bound to localhost. A LAN + Caddy alternative is documented in the plan. Never expose the server to the raw internet.

Current deployment (cameronspc)

The live server runs on cameronspc and is reachable tailnet-wide at:

https://cameronspc.tailfcc279.ts.net:8445

• Set up with tailscale serve --bg --https=8445 http://127.0.0.1:7777 (:443 was already taken by another service; --bg persists across reboots). Disable with tailscale serve --https=8445 off.
• Auth token lives at ~\.ade\token on cameronspc.
• The server itself is a detached process — after a reboot, restart it from the repo: cd apps\server; node dist\server.cjs serve --port 7777.
• On iPhone: connect Tailscale, open the URL in Safari, paste the token, then Share → Add to Home Screen for the PWA.

License

Argus (formerly ADE) is a modified derivative of ADE, which is itself a modified derivative of Superset (Copyright Superset, Inc.). It is distributed under the Elastic License 2.0 — see LICENSE.md, with the modification chain documented in NOTICE. Third-party dependency notices are in THIRD-PARTY-NOTICES.md. The agent memory architecture is adapted from NousResearch/hermes-agent (MIT).

Under ELv2 you may use, modify, and self-host Argus freely (including distributing it for others to self-host). You may not offer Argus to third parties as a hosted or managed service.