Agents in Weald
Last updated
A coding agent works inside Weald by reading and writing files in the project's .weald directory and by calling an MCP server the app runs on loopback. Weald is the server and the agent is the client, so nothing needs an account, a token or an internet route. The agent acts under a delegation issued by your device, which can narrow that device's authority and never widen it.
The directory
.weald sits in the repository, so the project record travels with the code and is readable without Weald running.
| Path | Holds |
|---|---|
tickets/ | One .wealdticket file per ticket: markdown with YAML frontmatter |
events.log | An append-only record of what happened |
chat/ | Signed channel and thread files |
agent-runs/, runs.json | Durable run records, so an overnight run survives a restart |
qa/ | QA run records and committed screenshot evidence |
plan.json, prompts.json | The time-boxed plan and saved prompts |
proposals/ | Model-drafted tickets, ignored by git, never applied without approval |
Ticket files are human-editable and round-trip byte-identically, because humans and agents both edit them and a formatter that reflows somebody else's file causes merge conflicts.
The MCP server
Weald runs a Streamable HTTP MCP server at http://127.0.0.1:47921/mcp. It binds loopback only and carries no auth token, because the socket is not reachable from off the machine.
Tools cover tickets, progress and status, attention, the panels the app draws, and agent-authored widgets. The tool listing is served in tiers so a client is not charged for descriptions it will not use, and calling a tool by name always works.
Which agents
Weald launches CLI agents rather than implementing one. Claude Code is the default, and opencode, Codex CLI, Gemini CLI, Cursor Agent, Amp, Aider and Crush are built in, alongside agents you define yourself.
Each capability is a template, so an agent that cannot resume a session says so in settings instead of producing a command line that fails. Weald does not edit another tool's configuration file for it: the connect step shows the one-liner to run and the config path to edit, and you decide.
What an agent may do
An agent's first connection asks a person, once, naming the workspace, the groups, the capabilities, the read scope and the expiry. Renewing inside the same scope never asks again; widening always does.
- Delegations expire. Twenty-four hours for an interactive agent, seven days for a long-running one.
- Three capabilities can never be delegated at all: admitting members, revoking members, and admin authority.
- A ticket transition is a capability in its own right, so an agent can be allowed to move a card to review without being allowed to move it to done.
Authorization is asymmetric, on purpose
An agent's writes apply immediately, because they are sanctioned work you asked for. Weald's own model-drafted suggestions are staged and require approval before they touch disk.
The origin field on a ticket is what makes the difference visible after the fact.
When Weald is closed
Agents do not depend on the app running. An agent that writes .weald files directly lands its changes, and Weald replays them from disk and from the event log the next time it opens.
That is what makes this a file format rather than an integration.
Watching a run
Every dispatch surface, the tray composer, a board handoff, a preset action, target mode, a QA pass, folds into one normalized activity row: source, title, detail, state, percent, project, ticket. Unattended runs report through the same path, so no feature can start one invisibly.
A run inspector window carries the log tail, the terminal phase and the tickets a run filed. Handing a card to an agent moves it to in progress and instructs the agent to land in review rather than in done, because a human closes work.
What is not built
A teammate cannot start an agent on your machine. Mentioning a remote agent renders, and nothing behind it is wired: a message arriving from the relay does not reach an agent responder. Making that safe is tracked as its own programme.
Nothing prevents a card being marked done over a failing QA verdict yet, either.