Sculptured docs

Concepts

The words Sculptured uses, how the parts connect, and what each status means.

A project holds a team's design and run history. Its agents work in folders you choose and pass results along the connections you draw. This page explains those parts and the labels you will see as the team runs.

Designing

WordWhat it is
ProjectOne team's design and its history. The Projects page, and the Projects menu in the top bar, list your projects.
TeamThe agents of a project and the connections between them, started and stopped together.
AgentOne worker with a name, a Job and a Folder. It runs on Claude (Claude Code), Codex or OpenCode (open models, see Open models with OpenCode).
JobThe agent's assignment, delivered when its work begins. An agent waiting for a handoff receives its Job with that handoff. See Designing teams.
FolderWhere the agent works. Agents use the project folder unless you give one its own. On a connected computer it must be inside a folder that computer allows.
GroupA box of agents inside a team, with its own color. Save a group to your Library to reuse it in other projects: see Reusable groups.
InputShared goals, links, notes and constraints. In an ordinary team, selected agents receive it; in a workflow, the dispatcher reads it when the team starts.

Connections

Arrows on the board say how agents relate.

ArrowEffect
hands work toWhen the source agent finishes a work turn, Sculptured passes its final reply to the receiving agent. The source starts first.
reports toDesign intent only. It documents the hierarchy; nothing is enforced.
watchesDesign intent only. Nothing is enforced.

A handoff is one piece of work passed along a "hands work to" arrow, recorded with its message. An arrow on the design does not prove a message was sent: the Run view shows the handoffs that actually happened.

Workflows (Advanced)

A workflow replaces ordinary arrows with stages. A dispatcher agent reads Input and splits the work into items. Each item moves through stages, and routes can branch on the outcome or loop back for another round, up to a round limit. A stage is run by one of:

StageSettled by
AgentAn agent, which reports the outcome.
Review panelSeveral reviewers, whose verdicts are combined.
CheckA command Sculptured runs, such as npm test. Its result is verified evidence.
Person decidesYou, with approve or rework and an optional note.
MergeSculptured, merging the item's branch back. A conflict sends it back.

An assembly agent finishes once every item is done. See Workflows.

Running

WordWhat it is
Start teamChecks the design, then starts each agent in order. The project's status, next to Start team, reads Draft · N to fix until the design can start, then Draft · ready to start.
Design and RunThe two views of a project. Design is the editable board. Run shows the agents that are running now, what each is doing, and the handoffs between them.
RunOne start-to-stop of a team. Each run's history is kept.
QuestionAn agent asking you for a decision. It shows as needs you until you answer, or until it times out and the agent decides for itself. See Questions and approvals.
Managed subagentAn agent another agent started with Sculptured's tools while the team runs. It shows in Run under its parent.
Own copyAn agent's own Git working copy of the project, so agents working at once don't overwrite each other.
Token useThe tokens each agent's CLI reports, shown live. Limits and estimates are on Limits and usage.

Agent states such as running, stopping or needs attention are listed on Agent states.

Computers

WordWhat it is
ComputerOne of your machines, connected to your account. The Computers page lists them.
RunnerThe background program on a computer that starts the agents, captures what they do and passes messages. Installed by the connect command.
Allowed foldersThe folders a computer lets agents start in, decided on that computer. By default, your home folder. Add more with sculptured allow <folder>.
AccessHow much agents may do once started. Full access (the default) lets them act as you do. Sandboxed makes Claude ask before risky actions and keeps Codex writing only inside its folder.
Run onWhich computer runs a team. With one connected computer, Automatic uses it.

The server can ask a computer to do something, but the computer has the last word. It refuses agents outside its allowed folders, and the server can lower access but never raise it.

Evidence and provenance

Progress labels describe where the work stands: Planned, In progress or Blocked, for example. Evidence labels describe how Sculptured obtained a fact. Read them together: an agent can finish a task without its result having been checked.

WordMeaning
Agent-reportedThe agent said so, for example "done" or "tests pass". A claim, not proof.
CapturedSculptured recorded it directly, such as a tool call and its result.
ObservedSeen on disk or in Git, such as a changed file.
EstimatedWorked out by a rule of thumb, such as a token count from text length.
VerifiedA check Sculptured ran passed; the result covers what that check tests.
UnknownNo supporting information is available.

Sharing

WordWhat it is
LibraryYour private collection of reusable groups.
CommunityThe shared catalog. A published group is a block: a definition only, which never starts agents by itself.
Team fileA project exported as a MADL document (.madl.yaml), an open format other tools can read.

How the parts connect

Hosted beta

flowchart LR
  B["Your browser"] -- "HTTPS, signed in" --> G["Gateway: app.usesculptured.com"]
  G -- "your requests only" --> I["Your own Sculptured: board, journal, workflows"]
  R["Runner on your computer"] -- "connects out through the gateway" --> I
  I -- "start, message, stop" --> R
  R --> C["Claude Code"]
  R --> X["Codex"]
  C -- "read and edit" --> F["Allowed folders"]
  X -- "read and edit" --> F

The hosted service signs you in and provides a separate Sculptured instance for your account's projects and run history. Your computer's runner opens an outbound connection to the service, so you do not need to open an inbound port. Agents run on your computer using its CLI sign-ins and folder permissions.

Self-hosted

flowchart LR
  B["Your browser"] -- "http://127.0.0.1:4410" --> S["sculptured serve: board, journal, workflows"]
  S -- "start, message, stop" --> R["Local runner"]
  R --> C["Claude Code"]
  R --> X["Codex"]
  C -- "read and edit" --> F["Your folders and Git"]
  X -- "read and edit" --> F
  R -- "every event" --> S

sculptured serve starts the app server and a runner on the same machine. Team designs and run history are stored locally. Claude Code and Codex still communicate with their providers; see Privacy for the data flow.

Next steps