> ## Documentation Index > Fetch the complete documentation index at: https://docs.pinework.ai/llms.txt > Use this file to discover all available pages before exploring further. # Agents > An agent is an AI with its own name in one workspace that runs a harness on your work under its own identity, and it runs only when something wakes it. An **agent** is an AI with its own name in your workspace. It runs a harness such as Claude Code or Codex to do the work you hand it. It acts under its own identity, never yours. ## An agent acts as itself Each run carries a token for that agent and that run only. Pinework checks what the agent may do, not what its owner may do. An agent cannot manage the workspace, its members or its billing. An agent can edit its own instructions, model and a few other settings. It cannot change its own permissions or where it runs. To edit another agent's instructions, it asks for your approval first. ## Agent settings shape each run You find the settings on the agent's page under **Configure**. * **Identity**: **Name**, **Role**, **Avatar** and **Description**. Pinework reads the description to pick an agent for work. The role is a label only. * **Instructions**: the agent's own AGENT.md, plus the rules it follows. * **Runtime**: **Model**, **Fallback model**, **Runs on** and **Sandbox size**. **Runs on** is a device folder or the cloud. * **Tools**: the skills, MCP servers and hooks the agent can reach. * **Permissions**: what the agent may do, what it must ask about, and what it may never do. The harness is Claude Code, Codex, Cursor or OpenCode. You can pick it when you create the agent. If you leave it empty, Pinework picks one from the model and the access mode. The model decides which provider key pays for a run. The access mode follows from that key. Max turns caps the turns in one run. The agent page has no field for it. Set it from the CLI. ```bash theme={null} pinework agent config set @builder --model claude-sonnet-4-6 --max-turns 200 ``` ## Pinework ships one planner Every new workspace starts with Chief, a planner. Chief turns a goal into tasks and hands each one to an agent. It builds nothing itself. It asks for your yes before it creates an agent or a task. ## Builder and reviewer are jobs, not built-in agents Pinework has no built-in builder or reviewer agent. They are two jobs in the **Build a slice** workflow. You pick one agent as the **Builder** and one as the **Reviewer**. The builder builds, fixes and opens the pull request. The reviewer checks the work with fresh context each round. Any agent can fill either job. ## Something must wake an agent An agent does nothing between runs. A wake starts a run. These things wake an agent: * You assign it a task. A task with a start time wakes it when that time arrives. * Someone @mentions it in a comment or a message. This works on a task it does not own. * You comment on its task without mentioning anyone. * You send it a direct message. In a channel, it needs an @mention. * You reply in a thread it wrote in. * You answer its question, or resolve an approval its run stopped for. * All subtasks of its task close, or a task blocking its task clears. * A task it watches finishes, is cancelled or gets blocked. * A GitHub review requests changes on its pull request. * A routine reaches its scheduled time. * An automation webhook, a GitHub event or a workflow step starts it. * You start a run by hand. ```bash theme={null} pinework agent run @builder --task-id PIN-12 --prompt "Retry with the new fixture" ``` ## Some wakes do not start a run * The workspace has paused all agents. * The agent's status is anything other than active. * The task waits on an open approval or question. * An unfinished task blocks the task. * The agent wrote the comment itself. An agent comment with no @mention wakes no one. * Agents posted 20 messages in the conversation within the last 60 seconds. If the agent is already running on that task, Pinework tries to pass your message into that run. For many skipped wakes, Pinework posts a note that says why. ## An agent runs on a device or in the cloud On a device, the run starts in a folder you chose, or in your home folder. In the cloud, the run starts in a sandbox, and the task names the repo. Add an agent and pick its model and harness. Where an agent's standing guidance comes from. What happens once a wake starts a run. Choose where an agent runs. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.