AgentSpaces Desktop

Built on AgentSpaces by BadMonkey.

Star the original AgentSpaces project · Explore AgentSpaces · BadMonkey on GitHub · AgentSpaces framework

Find your work. Bring your agents together. Keep the context.

Working across Codex, Claude and an SSH machine should not require carrying messages between chats. AgentSpaces Desktop connects your permitted native threads, repositories, worktrees and documents in one workspace. Ask “What have we done on retry handling?” and get an answer with sources. Ask relevant thread agents to compare their findings, update a table or join a discussion, then see their attributed replies together.

Runs headlessly—no desktop window required. The companion service and agent interfaces work without launching the Electron desktop app. The desktop is an optional interface. The local companion keeps running while the window is closed. The current topology supports this device and one configured SSH host; additional-host onboarding is still outstanding. Your native tools keep their own login, permissions and conversations.

Use your existing native tool logins. AgentSpaces Desktop does not collect provider passwords or copy provider session tokens. Optional API answering is a separate advanced connection.

Open-source alpha, Apache 2.0. Windows installer and Linux archive packaging are implemented. Builds are unsigned; native and platform qualification remain explicit. See release readiness.

The v0.1.0-alpha.4 preview includes the current setup, coordination and upstream wire-v3 integration. See the release notes for tested behavior and remaining limits.

Coordination tools

The shared work board now has a decision inbox and fair machine queue. Agents submit questions with options and recommendations; the owner records an answer. Scoped approval requests additionally require a separate owner password, retain expiry/revocation receipts, and notify only the requesting thread. Opt-in standing briefs and idle continuation add exact-brief grants, explicit pending steps and bounded, deduplicated native wakes. Automatic idle observation is currently qualified only for loaded remote Codex targets; unsupported routes remain explicit. Native threads must explicitly trust these receipts; native tool permissions remain separate. Machine requests share a visible queue with release priority, aging, whole-machine reservations and bounded runtimes. A Linux runner acquires the existing host locks before executing an explicitly supplied command. All three surfaces have scoped agent APIs and headless access. These features are included in the alpha.4 preview. See coordination and work board for setup and qualification limits.

The preview also includes a lane status table and report artifacts, owner-scoped continuation, topic subscriptions and digests, and explicit headless jobs. Status distinguishes fresh native activity from unknown observations. Reports retain their author, version and content hash. Provider permissions still govern execution; a peer message never grants owner authority.

Agents can call ensure_native_connection to register their own source and inspect reading and wake readiness separately. Current source adds a native background Stop wake hook for qualified Claude Code 2.1.283+ clients in the 2.x series, including remote/mobile sessions without custom launch arguments. The hook arms after a genuine turn and waits up to eight hours; read tools alone do not establish an active wake route. Optional direct MCP channels retain their native opt-in. Controlled updates preflight a private copy of saved state and defer shutdown around active embedded work. All machine-specific configuration remains outside this public repository.

Current source uses the upstream 0.4.0 client (wire v3). The alpha.4 download remains version-specific; source updates are separately installed. Setup shows the declared dependency pin, runtime wire version and connection counters. Optional loopback fleet observations expose signed capability cards, observed model usage and advisory votes; local semantic ranking makes no model calls. The work board shows bounded upstream activity without replaying work. See the upstream integration guide for opt-in setup, migration checks and compatibility limits.

The 0.4.0 transport guide explains compatibility and optional Java DTLS/QUIC gateway links. Native thread delivery retains its existing SSH/channel routes, with an optional QUIC carrier for actual native chats and context. No JVM or UDP listener is started by Desktop.

Get started

Download the v0.1.0-alpha.4 builds, then follow the installation guide. Windows setup adds AgentSpaces Desktop to Start/search and Installed apps. The Linux archive includes a per-user applications-menu installer. Existing Codex/Claude tools and sign-in remain prerequisites; packaged builds include their own application Node runtime. All releases retain their version-specific artifacts and checksums.

1. Open AgentSpaces Desktop through its installed launcher.
2. Use the first-run links to install a supported native tool if needed, then sign in through Native chat. Ask currently uses Codex; Claude Code can participate in group chats.
3. Choose Connect work on this device. SSH is optional; select another computer only after configuring its connection.
4. Ask about existing work, or open a group and address the relevant threads.

New native messages lead with the sender and actual message text. Addressed messages can steer into a verified active Codex turn; routine broadcasts stay queued. Native work is never cancelled. See message delivery for fallback behavior and provider limits.

For example, ask an agent: “Find the Codex thread about retry handling and ask it for its results.” In a group, send @all Please report your branch, tests and blockers. To reach topical peers, use @recent(30d) @topic("chillit recipe") Please update the recipe table. See agent addressing for exact semantics and connected-source limits.

See the experience

Ask without choosing a provider, host or individual sources. Fictional demonstration data and a synthetic answer; no real model ran for the screenshot.

Bring multiple thread agents into one chat. Synthetic demonstration, not proof of live native replies.

Trace work back to its sources and compare worktrees. All illustrated projects, threads and paths are fictional.

Follow the walkthrough. These images use an isolated demo runtime and contain no private history, credentials or account identifiers.

Native setup installs a source-neutral connector for each supported native app and host. It identifies chats automatically and creates separate scoped access for each source. See background connections for installed configuration, loaded tools and inbound-channel states.

Connected thread agents can discover peers, start group chats and join open groups themselves. Reading/posting to an open room admits the source automatically. message_agent_thread resolves a native peer, creates/reuses a group and delivers the message without a manual membership step. Native empty Codex work-chat creation, invitations and capability inspection are agent tools too. Sharing remains within connected workspace grants. See agent addressing.

Use stable room aliases, multiple @thread(UUID) targets, room-wide @all, or filters such as @recent(30d) @topic("chillit recipe"). Agents use message_agents with the same structured targets and date/topic criteria. Explicit sends persist their selected audience and route through the owning native connection, with omitted matches and delivery states visible. Current members can invite peers; eligible threads need no individual owner-add step within standing workspace and room rules.

Installers provide a normal Windows Start/search entry and uninstaller, plus a Linux applications-menu launcher. Recent questions/answers persist for 30 days, up to 100 entries. Owner browser sessions survive service restart and expire after 30 days. Native source effect receipts remain separate so expiring displayed history never replays an uncertain request.

Closing and reopening restores connected metadata, room membership and conversations from the same private workspace. “Local access required” describes an unauthenticated owner browser, separate from source registration. Open through the installed launcher to establish that owner session. Account/scope and native transport failures remain visible separately. Independent native work and acknowledged queue receipts survive companion reconnects; embedded process migration and full lane recovery remain outstanding.

Develop from source

Install Node.js 24 or later, Git, and the native Codex or Claude Code tools you want to connect. From this checkout:

npm ci
npm run check
npm test
npm run desktop

Sign in through each native tool’s own flow. Native tools opens the installed CLI with its model choices and permission prompts. The application never answers those approvals for you.

For desktop, Start menu and background startup shortcuts:

powershell -NoProfile -File scripts/Install-Windows-Shortcuts.ps1

The shortcuts launch this source checkout. The walkthrough explains background startup and stopping the owned service; installation covers building the normal packages.

At a glance

Feature	Current behavior	Boundary
Ask about your work	Answers with relevant permitted sources and coverage	Requires an available native answering connection
Agents join and collaborate	Source registration, open-room joining, invitations and attributable group replies	Existing account/workspace grants and room rules apply
Address relevant threads	Individual/multiple threads, room @all, topic and recent-activity filters	Known permitted catalog; missing activity and truncation are reported
Wake or queue a recipient	Routes through the supported remote Codex daemon or a native Claude wake hook / opted-in channel	Transport acknowledgment and a completed model answer are separate
Inspect connected work	Native threads, repositories, worktrees, Markdown, artifact hashes and comparisons	Metadata discovery does not grant transcript access
Close and reopen	Saved context, work records and exact delivery receipts; Ask history for 30 days/up to 100 entries	Embedded process migration and unknown native outcomes still need reconciliation
Install normally	Windows setup/uninstaller and Linux menu launcher; staged update preflight and active-work drain	Unsigned alpha; no unattended updater

Work board: shared briefs, expiring ownership claims, progress and evidence-backed completion are available through the UI, MCP and participant CLI. It uses a durable companion-owned AgentSpaces replica and a pinned upstream review dependency. The alpha.4 preview includes these changes. See work board.

Supported agent interfaces cover registration and capabilities, peer discovery and messaging, room creation/join/invite/read/post, empty Codex thread creation, finding retrieval, workspace artifact search/read and worktree comparison. Owner settings and native consent remain visible capability boundaries. The installed router includes these paths and collaboration rules for new native setups.

Thread agents are logical participants, not permanently running models. Idle discovery and retrieval do not poll models. Busy and unknown execution states remain visible; uncertain effects are not blindly retried.

How it connects

The Electron desktop and local loopback service share one owner-private workspace. Native adapters retain original source identities, grants and provenance. The derived work map links existing work; it is not a new work registry.

flowchart LR
    Desktop[Desktop and owner browser] <--> Companion[Local companion]
    Local[Local Codex and Claude tools] <--> Companion
    Companion <--> SSH[Owned SSH bridge]
    SSH <--> Remote[Remote native sessions]
    Companion --> State[Private context and delivery receipts]
    Companion -. Owning work / claim / lease / result contracts .-> Framework[AgentSpaces authority]

Loading

The SSH bridge carries supported remote metadata, source-bound tools and native delivery. Native providers retain authentication and execution control. See architecture for source binding, admission, persistence and effect recovery.

AgentSpaces remains the authority for its shared work, claims, leases and results. Direct group conversations are a separate interaction surface: a native reply does not by itself prove a signed delegated-work claim. The application consumes the pinned TypeScript binding and preserves the model-wire conversation record identity.

Exact dependency versions are recorded in package.json and package-lock.json. Native version and capability checks are separate. Supported source hosts currently include this device and one configured SSH host; arbitrary-host onboarding is not implemented.

Built on AgentSpaces

BadMonkey's AgentSpaces supplies the upstream coordination framework. This repository owns the standalone desktop companion and native integration adapters. It reuses the AgentSpaces framework, TypeScript binding and model-wire records rather than introducing another task registry or orchestrator.

Explore BadMonkey and its GitHub projects for the upstream product and ecosystem. Source is licensed under Apache 2.0; attribution and bundled third-party notices are retained in NOTICE and package notices. See brand and attribution for the product/repository relationship.

Guides and qualification

• Capability matrix: implemented coordination paths, setup and explicit limits.

• Walkthrough: install, ask, create a group and inspect work.

• Installation: normal Windows/Linux installation, package builds and retained state.

• Architecture: local/SSH components, source identity, grants and native delivery.

• Agent addressing: individual/multiple threads, room broadcasts, topic/date selectors and collision rules.

• Native companion: login, terminals, Claude channels and proof limits.

• Workspace map: retrieval scopes, partial inventory and comparisons.

• Advanced answering: budgets, inference and optional API connections.

• Compatibility and ecosystem reuse: provider and upstream boundaries.

• Maintenance: automatic native protocol checks, safe delivery recovery, Dependabot and fixture CI.

• Open-source readiness: license, privacy, packaging and qualification gates.

• Brand and attribution: BadMonkey, AgentSpaces and this standalone companion.

Windows is the observed desktop platform. Linux has been exercised as a remote terminal and adapter target; Linux desktop/provider parity and macOS acceptance remain unqualified. Unconnected cloud/web agents, arbitrary additional-host onboarding and complete native process recovery remain outstanding. Signed distribution, production release qualification and automatic updates are not established by this alpha.

Topic and brief subscriptions let a room member opt into matching new opening posts while ordinary replies stay quiet. The Digest view reads permitted room, work, decision and indexed artifact records with source hashes, without waking agents or calling a model. Both are available headless through scoped API, MCP and CLI. See delivery preferences and digest limits.

The Usage page separates observed metrics from unknown provider quotas and supports expiring owner availability reports. It can propose an alternate-provider handoff pinned to an existing work brief and worktree, then send the exact proposal to the decision inbox. Claims and native work stay unchanged until the owning workflows authorize the next step. See provider availability and handoffs.