A local workspace for personal AI agents. Configure each role's instructions, model, skills, and tools. Connect roles in a visual flow, run a task, and inspect its real conversations and evidence.
The web UI, API, and execution runner are separate. The runner owns tasks and persists their state in SQLite, so closing a browser or restarting the web server does not stop a task.
Supported target: macOS and Linux, arm64 or x64. The current end-to-end validation was performed on macOS arm64. Install Git and Node.js 20 or later for the bootstrap command.
node scripts/bootstrap.mjs
./studio install --frozen-lockfile
./studio setup
./studio build
./studio startOpen http://127.0.0.1:4183/. Setup installs the pinned Node and pnpm toolchain inside .local/tools, prepares native SQLite and terminal modules, builds k6 with a patched Go compiler, and installs Playwright Chromium. The first setup needs network access. It does not replace global Node, Codex, or Claude Code installations.
- In Connections, check your existing Codex or Claude Code subscription login, or enter a provider API key. The Sign in action opens the official CLI sign-in flow.
- In Agent library, open Edit agent to select a connection, model, and permission level. Flows reuse these saved agents. The initial flow includes both Codex and Claude presets; change them if you want to use one provider.
- Add a project folder. Choose Local to use it directly, or New worktree to create a Git branch and working directory when the task starts.
- Attach local skills if needed. Each run freezes its selected skill versions and supporting text files.
- Describe a task and run the flow. The default permission level requests file-write approval according to workspace settings, then asks separately for shell commands and external HTTP targets.
API keys are kept in runner memory. Enter them again after a runner restart. Subscription credentials remain in the official CLI's credential store. Disconnecting a connection in Studio does not log the CLI out. Billing modes never switch automatically.
Choose Defaults > Display language to switch between English and Korean. The choice is saved in this workspace's local SQLite database and survives reloads and workspace resets. Existing workspaces default to English.
Menus, settings, task controls, status labels, dates, and counts follow the selected language. Project names, agent names, instructions, skill content, conversations, and artifacts retain their original text. Provider diagnostics and terminal output remain as reported by the runtime. Changing the UI language does not change agent instructions or response language.
Open an agent's Conversation tab in the normal or fullscreen layout. While that agent is working, choose how to send the next instruction:
- Add to queue finishes the current turn and processes pending instructions in order, in the same provider session. These instructions finish before the role hands off to another agent.
- Adjust current work interrupts the current turn and its foreground tools, then runs the new instruction ahead of the queue. Existing file changes remain in place. Studio waits for the interruption before starting another turn.
The pending list supports cancellation and holds up to 20 instructions. Drafts stay separate for each agent. Ctrl/Cmd + Enter sends with the selected mode. Only the agent currently working accepts live instructions; other started agents can receive follow-up messages when the workflow is idle.
Instructions use the agent's frozen permissions and skills. They cannot bypass a plan review or expand tool access. Follow-up conversations from a completed or paused workflow do not start later agents. Stop reply cancels that reply's remaining queue, while workflow cancellation stops all pending instructions for the task. Cancelled messages remain in the conversation.
Pending instructions survive a page reload. If the runner restarts or cannot confirm a stop, Studio holds the task for inspection and does not replay commands. Inspect the provider and project before cancelling that interrupted task and starting a new conversation.
In Flows, connect an output to multiple inputs, or select an agent and check its Next agents. Uncheck a target to remove its connection. A join starts after all connected predecessors have completed and their human reviews are approved. Ordinary connections cannot form cycles; use the existing bounded revision rules for a return path. Parallel agents limits a flow to 1-8 simultaneous role turns, independently of the workspace's concurrent-task limit.
Graph runs capture the selected project's source in a private local Git repository. Each agent receives an isolated working folder based on its predecessors' saved results. Existing tracked and visible untracked source files are included. Dependency folders, generated output, secret paths and symlinks are excluded. Agents must prepare dependencies and test servers inside their working folder when needed. Your source repository's branches, index and commit history are not used for these private snapshots.
At a join, Studio combines the predecessor changes. Contributors inspect the actual combined version and return explicit pass or revise decisions. QA contributors with execution tools must record execution evidence against that version. A writable contributor or upstream agent resolves conflicts and disagreements using its frozen permissions. Every contributor must agree on the same file version. After three unsuccessful rounds, Studio requests human revision instead of silently choosing a result. Merge conversations, votes, branch changes and inspection receipts remain available in the task UI.
After all branches and reviews finish, Studio applies the combined patch to the task's original working folder. If that folder changed during execution, publication stops for inspection. Private workspaces remain available with the task's evidence. A graph session's later follow-up edits remain in its branch and require another review and merge; they do not silently overwrite the original project. Merge sessions accept live instructions while running; later follow-ups use the original agent session.
Each running branch has its own message queue, interrupt state, provider session, permission requests and conversation. Handoff shows its working folder, and the fullscreen source reader follows the selected branch. Revisions invalidate only the target and its dependent branches. Existing flows and runs without saved graph connections retain their sequential behavior.
Open Agent library > Edit agent > Parallel delegation. Enable child agents, choose their saved presets, and set a concurrency limit from 1 to 3. Existing presets keep delegation disabled. Changes apply to new tasks; a running task retains its frozen instructions, models, skills, and permissions.
The parent agent decides which independent work to delegate. It can use its own preset or the other presets you allow. Each child gets a separate conversation and a bounded objective. A child cannot create more children. Each parent step can create up to 12 children in total, with no more than the configured number active at once. The runner permits at most 24 active children across tasks. Provider quotas and machine resources remain shared.
flowchart LR
P[Parent agent] --> A[Child: implementation]
P --> B[Child: review]
P --> C[Child: test]
A --> J[Parent inspects and collects results]
B --> J
C --> J
J --> V[Verify combined changes]
V --> H[Existing workflow handoff or human review]
Children work from isolated snapshots of the parent's current files, including uncommitted changes. For a Git project, select its repository root and create at least one commit first. Action-capable children run in separate Git worktrees. Read-only children can also use a bounded copy of a non-Git project. Secret paths and generated directories are excluded from snapshots; non-Git copies also exclude hidden entries and symlinks.
Child tools are limited to those enabled for both the parent and the selected child preset. Child permissions cannot exceed the parent and never inherit Bypass permissions. Read-only delegation blocks writes and action tools. Studio records child approvals, tool receipts, findings, and artifacts separately.
The parent must inspect and accept or discard every child result before handing off. Accepting a successful result copies its evidence and applies any changed files only if those files still match the child's starting snapshot. Conflicts stop collection instead of overwriting parent edits. After integrating code, the parent must record a successful execution check against the combined files. Child worktrees remain available for inspection; they are not automatically deleted.
Open a child under its parent in the task's session list or agent map. Conversation, elapsed time, tool evidence, artifacts, and fullscreen source previews belong to that selected child. Add to queue and Adjust current work target the selected active session. Interrupting the parent stops its children before applying the new instruction; interrupting a child leaves its siblings running. Task cancellation stops the whole group. Completed child sessions remain readable; ask the parent to review them or delegate another task for further work.
An interrupted runner does not automatically replay child work or repeat an uncertain integration. Inspect the saved sessions and files before starting a replacement task. Human plan locks and workflow reviews still apply.
Choose Defaults > Concurrent tasks to set a workspace limit from 1 to 8. Existing workspaces start at 1. The home screen shows the active count, and Tasks lets you open and control each task independently. Approvals, reviews, cancellation, provider sessions, and terminal control belong to the selected task.
Use separate project folders or New worktree for tasks that run together. Studio rejects identical or overlapping execution folders, including symlinks. Each new worktree has its own folder and branch. Paused tasks, pending approvals, human reviews, and tasks awaiting recovery still occupy a slot. Lowering the limit does not stop existing tasks; it prevents new starts until a slot is available. Provider account limits and machine resources remain shared.
Open Agent library > Edit agent. Changes apply to future runs. Active runs keep their saved settings, available under Handoff.
| Permission level | Behavior |
|---|---|
| Ask for approval | Uses the workspace file-write approval setting. Each shell command and external HTTP target requests approval. |
| Read only | Allows selected file-reading and artifact tools. Blocks writes, shell commands, HTTP calls, and browser actions. |
| Project automation | Pre-approves selected file-write tools and sandboxed shell commands, including command network access. External HTTP tool targets still request approval. |
| Bypass permissions | Skips approval prompts. Enabled file tools can access paths outside the project, including hidden and secret files. Shell commands run without a sandbox as your OS user. HTTP and browser tools can access external targets. |
Tool checkboxes continue to limit which tools each agent can call. Read only temporarily disables action tools without losing their selections. Project automation retains project file boundaries and the Codex shell sandbox. Bypass permissions applies only to the selected agent and takes effect on the next run; it does not change existing runs or grant approval to other agents. An enabled Shell tool in bypass mode has your OS user's file and network access even if the Write files tool is disabled. Load tests remain limited to loopback targets and their existing load limits.
Codex agents also have Fast mode: Default follows local Codex settings, On requests faster processing, and Off explicitly selects standard speed. Studio checks runtime model support before inference and records the selected session tier. Unsupported requests fail with an explanation. Fast mode consumes more subscription usage or incurs higher API pricing; see OpenAI's speed guide. Claude agents do not show this Codex setting.
Open Flows and select a step. After this step controls when a person reviews its outputs: continue automatically, review every completion, or review when issues remain. Enable Lock reviewed outputs to approve the exact output versions. These rules belong to the flow, while prompts, models, skills, and tool permissions stay in Agent library. Active tasks keep the flow rules saved at their start.
Suggested rules adds a locked Planner review, a shared Coder / Reviewer / Tester loop with up to three automatic revisions, and a final human review. Review the proposed settings before applying them. Existing flows remain automatic until you save rules.
When a task needs review, open Review outputs. Read the plan and QA sheet, request changes with feedback, or choose Lock only to approve and remain paused. Lock and continue starts the next step. Later drafts can be compared with earlier drafts, and Attempts retains previous conversations and outputs. Human review does not grant file, shell, or network permissions.
Planner reports unresolved choices as decision cards above the plan. Each card includes the options, a recommendation, and whether an answer is required before coding. Choose an option or type an answer, then select Update plan with answers. You can answer a few at a time. Planner returns the complete updated plan and QA sheet; the task stays at review. Required choices disable both lock actions, and the runner rejects approval until they are resolved in the revised draft. A recommendation is not an approved choice. Follow-up explanations without revised documents do not clear pending decisions.
To plan with the agent before coding, set the Planner step to Review before continuing, enable Lock reviewed outputs, and return revisions to the Planner. Its review panel accepts questions and changes; each submission produces a new draft while Coder stays queued. Lock only keeps Coder waiting until you resume. Existing flows retain their saved rules, so check the selected flow before starting. Completed runs retain their original snapshots.
Attach the relevant architecture skills to both Planner and Coder when the plan must follow a specific codebase. Ask Planner to specify the package layout, responsibilities, transaction boundaries, and test criteria, then inspect those choices before locking. Skill instructions guide implementation; they do not replace code review or test evidence.
Under Automatic revisions, choose an earlier step and a limit from 1 to 10. A revise result reruns that interval in fresh sessions before the human checkpoint. The limit counts extra attempts after the first pass through the interval. At the limit, the task either requests human feedback or stops. Human feedback authorizes one more attempt without resetting the automatic limit. Select Agents sharing this revision limit to let Reviewer and Tester both return to Coder. All selected agents share the same limit and limit action. Changing the limit from any member updates the whole group. Groups with different return targets cannot overlap. Execution errors stop the task instead of consuming revision attempts.
For example, if Reviewer requests one fix and Tester then requests another, the group has used two automatic revisions. Every return reruns Coder, Reviewer, and any remaining checks in order. The project folder stays the same; each repeated step gets a fresh session. Prior findings and evidence are included in the repeated checks, even after their original outputs move to history.
flowchart LR
P[Planner] --> H[Human plan lock]
H --> C[Coder]
C --> R[Reviewer]
C -->|Plan needs changes| P
R -->|Pass| T[Tester]
R -->|Needs changes| C
T -->|Needs changes| C
T -->|Pass| F[Final review]
The flow canvas draws return arrows. The task shows the shared count, the latest return reason, and Revisions with the source agent, target agent, code reference, findings, and evidence links. Open source attempt opens the conversation that requested the fix. Findings remain agent reports; recorded tool evidence and fresh checks establish whether a fix worked.
At a human review limit, enter feedback and choose Run one more revision or Revisit plan. Revisiting the plan clears the old lock and holds Coder until the new plan is approved. Neither action resets the automatic revision counter. Cancellation remains available from the task controls.
If an automatic step reports a change to a locked plan, including a blocked implementation caused by that plan conflict, Studio sends its findings and the approved outputs back to the Planner automatically. Coder does not request a separate human review. Planner revises the plan and QA sheet, then waits for a new plan approval before coding can resume. Explicit reviews on the reporting step still apply. If no upstream locked Planner is available, Studio holds the scope change for a person to resolve.
Revision instructions apply only to the agent receiving that revision. Later agents receive the relevant findings and prior output IDs as evidence. A Planner-only instruction to stop before implementation is not forwarded as an instruction to Coder.
Changes to an approved plan require another human review at the Planner checkpoint. Approval checks the reviewed output versions and project fingerprint; changed files require a fresh revision. Pending human reviews survive a runner restart. Superseded outputs remain in history and are not passed forward as current evidence.
- Project registration, folder browsing, branch validation, local execution, and real worktree creation.
- Selective import of local Codex and Claude Code project folders, with deduplication and access to previously imported conversation snapshots.
- Multiple flows with create, rename, duplicate, archive, restore, node ordering, fan-out connections, joins, isolated parallel branches, merge agreement, zoom, and JSON export.
- Six role presets with editable prompts, provider, model, tool permissions, and local skill bindings.
- A local skill catalog with search, source folders, version checks, frozen snapshots, and previous-run inspection.
- Real execution, approval, pause at a step boundary, resume, cancel, history, and persisted settings.
- Separate role conversations, tool receipts, bounded handoffs, provider token usage when available, and downloadable outputs.
- Real API requests, bounded k6 tests, Playwright browser actions, HTTP status capture, accessibility observations, and screenshots.
- Native Codex terminals attached to the same app-server and thread. Automatic execution pauses while the terminal controls the session.
The default roles are Planner, Coder, Reviewer, Backend QA, Frontend QA, and Documenter. Each step opens a fresh provider session. A completed agent report is distinct from tool evidence; the UI labels both. A blocked or invalid report never becomes a successful step.
Waiting screens show animated activity and elapsed time. Buttons show when a request is in progress and prevent duplicate submissions. Task preparation follows the actual project, skill, and runner requests; it does not invent a completion percentage. Closing a discovery dialog lets you keep working while its request finishes. Animations respect your system's reduced-motion setting.
Pause the task and wait for its current step to finish. Open Terminal on a started Codex session. Closing this view keeps its PTY alive. Use Return control to Studio before resuming automatic steps. An external terminal can attach to the same PTY:
./studio terminal RUN_IDA runner restart preserves a pending human review or a paused Studio step boundary. Interrupted execution requires reconciliation: Studio checks the saved provider thread, turn, account, project path, and recorded evidence. A completed exact turn or saved step boundary can be recovered. Missing, active, or ambiguous turns are not replayed. Review changed files before cancelling an uncertain run and starting a new one.
Native Claude terminal sharing, control of externally owned CLI sessions, and automatic synchronization with the OpenAI Codex desktop app are not supported. Browser QA uses Playwright through the runner.
Click the import icon immediately to the left of + beside Projects in the sidebar. Search by project name or folder path, filter by Codex or Claude Code, and select up to 100 projects. The list shows one row per folder and excludes unavailable folders. Projects already in Studio are marked and cannot be selected again.
Studio discovers folders from Codex's local catalog and Claude Code's local history, then registers the selected folders in its workspace. Git worktrees are grouped under their original working folder using their shared Git metadata. Separate repositories with the same name stay separate. Conversation history stays in the source app. Importing does not start a model, resume a session, or change project files. Existing project settings are preserved.
Previously imported conversation snapshots remain accessible from Imported sessions, which appears when saved snapshots exist. Local storage formats can change with provider updates; discovery reports read failures instead of inventing missing projects.
./studio check
./studio build
./studio test
./studio audit --audit-level=low
./studio audit:k6Tests use temporary projects and local HTTP targets. The normal test suite does not call a model. Optional probes under scripts/ use an existing Codex subscription and must be run deliberately. See validation for evidence and limits.
Set AGENT_STUDIO_PORT to choose a port, and AGENT_STUDIO_DATA_DIR to isolate a workspace. Both must be set consistently for the server, runner, terminal command, and stop command. The default state directory is .local/data; generated worktrees, screenshots, skill snapshots, and logs stay local and are ignored by Git.
Ctrl+C stops the web server while leaving the runner alive. Cancel a task in the UI, or use ./studio stop to cancel all active tasks and stop that workspace's runner. Existing project changes and saved task records are preserved.
See architecture, security, and open-source sources. The original prototype remains a separate design reference and simulator.
MIT. External runtimes and dependencies retain their own licenses and terms.