@aetheros/workspace

The agent workspace: a local app where your agents chat with you, each with its own model, and anything they want to change waits in a Review queue until you approve it.

aether workspace init   # writes editable agents to .aether/agents/ (never overwrites)
aether workspace packs  # lists the department packs; aether workspace init --pack sales adds one
aether workspace        # http://127.0.0.1:4850/ (add --no-memory to run without memory)

Command centre (front page, /). Team by department (.aether/departments.json, with sensible defaults), the assistant orb, chat with "answered by · cost", Review cards that show the change before Approve, budget, history and a build track. Five styles, three layouts and round or square corners (project choice in .aether/brand.json, personal choice in the browser), voice (Talk, wake word, spoken Review with "confirm") and quick actions (type /; .aether/actions/*.json), plus an Agent card (job, model word, tools, what it may edit, skills, last runs; running agents glow "working now"), a read-only Files viewer with "ask to change this" (through Review), plus Project panels (rules from CLAUDE.md/AGENTS.md/HANDOVER.md, your owner list and ideas) and a phone layout with a tab bar, plus a build track (steps from .aether/pipeline.json, current step from aether step events and GitHub) and a Run panel (buttons for package.json scripts and .aether/commands.json, live output), plus a status strip (site checks from .aether/status.json, and with GITHUB_TOKEN the sprint, pull requests, needs-owner issues and the next step from HANDOVER.md). Everything below describes the original workspace page, which is now at /admin.

What you get (at /admin):

• Agents (left): + New agent and Edit this agent open a form in the page, so you don't need to edit files by hand. Each agent file in .aether/agents/ has a name, short description, instructions, provider (claude, openai, google, xai, mistral or local), a model or a tier (cheap, balanced, strong, picked from the model catalog), up to three fallbacks, colour and the tools it may use. Without files you get two defaults: your brand's assistant and a Reviewer.
• Conversations (middle): kept only on this computer in .aether/local/ (git-ignored). Replies stream in as they're written. Under each reply a small line shows which model answered; after a fallback it also says which model was unavailable and why.
• Review (tab with a badge): when an agent wants to change something, for example adding an item to the owner list, the request waits with exactly what it wants to do. Approve runs it and Deny tells the agent it was refused. Requests left undecided are denied after 10 minutes. Pending requests and recent decisions are saved in .aether/local/ (git-ignored), so a restart doesn't lose them. A request from before a restart is marked as such: approving it runs it then and adds the result to its conversation. It expires 24 hours after it was asked.

Built-in tools (more come with integrations). An agent only gets the tools listed in its file; the write tools are not given to the default agents, so add them in the edit form when you want an agent to use them: | Tool | Effect | What it does | |---|---|---| | project.handover | read | Reads HANDOVER.md | | project.read_file | read | Reads a project text file up to 100 KB. Never .env files, .git, local data, keys or anything outside the project. | | project.list_files | read | Lists one project folder's files and folders, with the same exclusions | | project.search | read | Finds text in project files, up to 50 file:line: text matches, with the same exclusions; symlinks are not followed | | git.status | read | Branch, changed files and the last 8 commits; runs git directly (no shell) and changes nothing | | owner.list | read | Open owner tasks by group and ideas waiting for a decision | | owner.add_item | write: waits for Review | Adds an item to the owner list | | memory.read | read | The agent's own notes and the shared ones | | memory.search | read | Finds the agent's own and shared notes by words, best match first (local matching, nothing leaves the machine) | | memory.save | write: waits for Review | Remembers a note by name, or replaces it; shared: true makes it visible to every agent | | memory.forget | write: waits for Review | Forgets a note by name | | project.write_file | write: waits for Review | Creates or replaces a project text file (up to 100 KB). Review shows "Create" or "Replace", the line counts and the full new text. Never .env files, keys, .git, node_modules, .aether/local, .aether/agents (an agent could give itself tools), git hooks or .github/workflows (they run with repository secrets). No writing through symlinks; written atomically. | | github.create_issue | write: waits for Review | Opens an issue (title, text, labels) in the repository from AETHER_GITHUB_REPO or the github.com origin remote, using GITHUB_TOKEN (or GH_TOKEN). Review shows the repository, title, labels and text. | | flow.run | write: waits for Review | Runs a project flow pack (all flows or the ones named) against localhost or the pack's allowedHosts, saves the report in .aether/runs/ and returns the results. Review shows the pack, its address and the flows. |

Memory (tab): notes per agent, plus shared notes every agent sees.

• Each agent gets its own notes and the shared ones in its instructions for every conversation (up to 6,000 characters).
• In the Memory tab you see every note and can add, edit or delete it directly. Saving sends the version you started from, so if the note changed meanwhile your edit is refused instead of overwriting it.
• What an agent wants to remember or forget waits in Review, showing the exact text. An agent can only read its own and shared notes; the kernel's access policy enforces that, not just the page.
• Notes are encrypted (AES-256-GCM, through @aetheros/kernel-runtime/agent-memory) in .aether/local/workspace/memory.json, which is git-ignored. The key is kept outside the project: AETHER_MEMORY_KEY (32 bytes, base64) if set, otherwise a per-project key file in ~/.aether/keys/ readable only by you. Losing the key loses the notes; back it up with your other secrets.
• The default assistant has the memory tools; give them to other agents in the edit form.
• Search: the Memory tab has a search box; notes are ranked by how many of your words they contain (word starts count, so "pref" finds "preferences"). Plain local matching, no embeddings.
• Suggested notes: the Suggest notes button in a conversation, or starting a new conversation after at least 4 new messages, asks the agent's cheap-tier model for up to 3 notes worth remembering. Each suggestion waits in Review as a normal memory.save ("Suggested from a conversation"), so nothing is remembered without your approval. The call counts toward the agent's daily budget. It needs the agent's memory.save tool; switch it off per agent with "suggestNotes": false (or the checkbox in the edit form).

Attachments: attach text files or images to a message (the Attach button, or drop files on the chat).

• Up to 5 files per message, 1 MB each. Whether a file is text or an image is decided from its bytes (PNG, JPEG, GIF, WebP; text must be UTF-8), never from its name. Anything else is refused.
• Files are saved by id in .aether/local/workspace/attachments/<conversation>/ (git-ignored); the conversation only records names and sizes.
• Text files go into the prompt (up to 100,000 characters each), also on later turns. Images go only to models that read them (the model catalog's vision), and only with the newest message, so they aren't paid for on every turn. If any model in the agent's fallback chain can't see images, images aren't sent and the model is told an image was attached.
• Downloads come back as plain text or the image itself, with a sandboxing CSP, never as a page.

Search conversations: the search box above the conversation list searches titles, messages and attached file names of every local conversation. Every word must match, in any case; matches are highlighted, and opening a result jumps to the matching message. Plain text, on this computer.

Agent teams: give an agent a team (in its file or the edit form) and it gets a team.ask tool to hand a task to a teammate and use the answer.

• The hand-off runs as the teammate's own conversation ("From Lead: …"), with the teammate's model, tools and Review.
• Only listed teammates can be asked. An agent can't appear twice in one chain, so there are no loops, and chains go at most 3 agents deep.
• Each hand-off is written to .aether/local/events.jsonl with agent names only, never the task text. The Control Room's Agent team card shows who handed what to whom and whether it finished.
• The default assistant can ask the Reviewer.
• In the page, the asking conversation lists each hand-off ("Asked Writer · answered") with a link to the teammate's conversation, and that conversation links back ("Handed over by Lead").

Budgets: give an agent dailyBudgetUsd (in its file or the edit form) and it stops answering once that day's spend (UTC) reaches it, both in direct chats and for hand-offs from teammates. The asking agent gets the refusal as the tool result.

• Spend is worked out from each reply's token usage and the model catalog price of the model that answered. It's kept in .aether/local/workspace/spend.json (git-ignored) for 31 days.
• Replies from models without a catalog price are counted separately, never guessed. Add the price in .aether/models.json to count them.
• A reply that is already running finishes even if it goes over; the next message is refused.
• The agent list shows today's spend, for example "today $0.42 of $5.00".

How it's built: every tool call goes through Aevron's approval. An agent can only use the tools listed in its own file. Reads run at once and writes wait for a person.

Models: Claude agents use ANTHROPIC_API_KEY (default model claude-opus-5-5, or set model or tier per agent). Other providers need their key (see models) and a model or tier. With fallbacks, the next model answers when one is busy or down:

{"schemaVersion": 1, "id": "helper", "name": "Helper", "instructions": "Answer briefly.", "provider": "claude", "tier": "cheap",
 "fallbacks": [{"provider": "mistral", "model": "mistral-large-4"}, {"provider": "local", "tier": "cheap"}]}

Fallback never happens after a tool ran or after reply text was shown. Agents with tools can fall back to any provider, because every adapter supports tools; a local model with "tools": false in the catalog is skipped.

Safety:

• localhost only, with a Host check
• a per-run token on every API call and a nonce CSP for the page script
• agent instructions are only sent to the page when you open an agent's edit form, never in the agent list
• all text is written as plain text, never as HTML

Limitations (first slice):

• no routines yet
• integrations and agent teams are planned (see the roadmap)