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. You start it with an npm script from your toolkit checkout (the aios-workspace folder that has package.json), pointing --repo at your workspace:

cd path/to/aios-workspace          # the toolkit checkout (has package.json)
npm run gui -- --repo ~/Projects/your-workspace

--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. Run plain npm run gui (it builds the client first); --skip-build is only for the packaged desktop shell, which ships a prebuilt client.

Where the cockpit lives

The cockpit is being split into its own repository, aiosbrain/aios-workspace-gui. In the current release the in-tree gui/ + src-tauri/ trees inside aios-workspace are still present and authoritative — npm run gui from a Workspace toolkit checkout works unchanged. Their deletion from the core repo is a deferred follow-up.

A standalone install from the GUI repo must be told where your toolkit checkout lives: pass --toolkit-dir <path> or set AIOS_TOOLKIT_DIR. The built-in relative fallback only resolves when the GUI runs in-tree inside the aios-workspace repo — outside that layout the server stops with an actionable error instead of guessing.

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 (npm run gui) 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.