The Cockpit

The cockpit is the local web GUI for your workspace. It drives this repo through the Claude Agent SDK — so the agent has the same skills, governance, and sync that your terminal does, with a friendlier surface on top.

Run it

The cockpit is not an aios CLI command — there is no aios cockpit or aios gui. It lives in its own repository, aiosbrain/aios-workspace-gui. Clone it, build the web client once, then start the server pointing --repo at your workspace and --toolkit-dir at your toolkit checkout:

git clone https://github.com/aiosbrain/aios-workspace-gui.git
cd aios-workspace-gui
npm install
npm run build:client               # once, and after every pull

node gui/server/index.mjs \
  --repo ~/Projects/your-workspace \
  --toolkit-dir path/to/aios-workspace

--toolkit-dir is how the cockpit finds the aios CLI it drives. You can set AIOS_TOOLKIT_DIR instead of passing the flag. A valid toolkit checkout contains scripts/aios.mjs, scaffold/, and a root package.json; point either at something else and the server stops with an actionable error rather than guessing.

--repo must be a real workspace — the folder that contains aios.yaml (next to workspace.yaml). Point it anywhere else and the launcher stops before starting:

error: <path> does not look like an AIOS workspace (no aios.yaml/workspace.yaml/project.yaml/engagement.yaml)

On success it builds the web client, loads your workspace .env, and prints the URL to open — with a fresh token each run:

aios-workspace GUI
repo:  /Users/you/Projects/your-workspace
open:  http://127.0.0.1:8790/?token=<random>

Open that URL. Use the one it prints each time — the token rotates on every launch, so an old link won’t authenticate. Change the port with --port 8790.

Note

The cockpit runs locally and is token-gated, bound to 127.0.0.1 only. It talks to your repo on your machine; workspace file content is not uploaded until you deliberately run an eligible aios push. Online commands can still transmit their own request data.

Troubleshooting

• does not look like an AIOS workspace — --repo isn’t a workspace. Point it at the folder that holds aios.yaml — not an empty scaffold that only has a .aios/ directory.
• AIOS GUI runtime is incomplete. Missing: … — Chat needs Claude’s native executable. Confirm claude --version works, then, in the toolkit, run npm install --include=optional and relaunch. Never install the toolkit with --omit=optional — that strips the native executable Chat requires.
• Blank page or 404 after it starts — the web client wasn’t built. The server serves the prebuilt gui/client/dist; it does not build on launch. Run npm run build:client in the GUI repo and reload.
• An error naming a missing toolkit — --toolkit-dir / AIOS_TOOLKIT_DIR isn’t a toolkit checkout. Point it at the aios-workspace folder holding scripts/aios.mjs and scaffold/.

Where the cockpit lives

The cockpit lives in its own repository, aiosbrain/aios-workspace-gui — the client, the server, and the Tauri desktop shell. That repo is the only copy. The gui/ and src-tauri/ trees were removed from aios-workspace, so there is nothing to run from a toolkit checkout.

Because the cockpit and the toolkit are now separate checkouts, the cockpit must always be told where the toolkit is: pass --toolkit-dir <path> or set AIOS_TOOLKIT_DIR. There is no longer a layout in which it can infer one.

Caution

The desktop (Tauri) shell currently runs in adjacent-checkout mode only — it needs a Workspace toolkit checkout next to it and is not yet a self-contained app. Treat it as a preview; the browser cockpit is the supported surface this release.

Chat

Pick your model — and switch anytime

The chat header has a model picker with two options:

• Sonnet 4.6 — the default. Fast and cheap; the right choice for most work.
• Opus 4.8 — for harder reasoning.

You can switch mid-session with no reconnect — the new model applies to your next message. Your choice persists to agent_model in aios.yaml.

Resumable Chats

Every conversation is saved. The Chats sidebar lists them newest-first, titled from each chat’s first message. Reopen one to replay its transcript and resume the same session; hit + New chat to start fresh. The cockpit reopens your last chat when you reload.

Context (est.) meter

A small context (est.) meter shows roughly how much of the model’s window your last turn used (e.g. ~45k / 200k). It’s an estimate — a per-turn proxy, not a live running total — so you can tell when a chat is getting heavy.

Markdown replies

Assistant replies render as GitHub-flavored markdown — tables, lists, and code — not raw text. Links open in a new tab.

Personality

Open Settings → Personality to choose the agent’s voice:

Personality	Voice
AIOS (default)	Calm, structured, governance-aware
Analyst	Rigorous and cited — weighs evidence, hedges honestly
Coach	Warm and encouraging — asks sharp questions
Operator	Terse and action-first — answers, then next steps

Caution

Personality is a style layer appended to the system prompt. It never overrides your workspace rules, CLAUDE.md, or skills. Picking a personality starts a new chat so the new voice takes effect.

Skills

The Skills tab installs official Anthropic skills, vendored from anthropics/skills and hash-locked to a pinned upstream commit. All are Apache-2.0.

Installing copies the skill into .claude/skills/ so the agent can use it — behind an integrity check, a collision guard, and an append-only install ledger. Removal is safe-only: it won’t delete a skill you’ve edited locally.

The vendored set:

• skill-creator — build and improve skills
• mcp-builder — build MCP servers
• web-artifacts-builder — build self-contained web artifacts
• claude-api — Claude API / Anthropic SDK reference
• frontend-design — guidance for distinctive UI

Document skills point to Claude

Anthropic’s document skills — Word (docx), Excel (xlsx), PowerPoint (pptx), and PDF (pdf) — are proprietary and Anthropic-hosted, so they are not copied into your repo. They appear under Documents — available in Claude with an Enable in Claude ↗ link. Use them inside Claude rather than installing them here.

Community skills are scanned before install

Skills from beyond the official library are installed through a community trust tier: before anything is copied in, a static safety scan reads the skill’s SKILL.md and every bundled file and flags bundled code (including extensionless shebang scripts), network calls, secret reads, external URLs, and prompt-injection — showing each finding as file:line. You review the findings and consent before install; a high-risk skill requires a typed confirmation.

Caution

The scan is advisory — scanners can be bypassed, so provenance and your own review remain the real trust anchor. Official skills stay one-click.

Marketplace skills (first-party)

The marketplace tier installs first-party Anthropic skills from claude-plugins-official via fetch-on-install: the skill is fetched at a pinned repo@commit and its bytes are verified against a declared hash before anything is copied in (install is refused on mismatch). It sits between official (vendored, one-click) and community (scanned, typed-consent) in the trust order.

Onboarding: draft your profile from a link

On first run, the cockpit can set up your profile for you. Under or draft it from a link, paste a company or profile URL and click Draft →.

The agent reads that one page with the firecrawl-direct skill (via Firecrawl) and extracts structured facts — who you are, your company, your focus areas, the tools you use — then drafts your durable memory (.claude/memory/USER.md + WORKSPACE.md). You confirm before anything is written.

It also matches the tools it detected to connectable integrations and offers to connect them in the Integrations tab — advisory, and only ever for integrations that can actually be connected. It never connects anything for you.

Caution

Scraped page content is treated as facts to confirm, never as instructions, and only the single URL you supply is read (no crawling). Connect Firecrawl in Integrations first.