Documentation
One all-purpose session accumulates every job and an ever-growing context. RandComp Studio lets you split research, product, implementation, and review into focused role sessions, then keeps their tasks, messages, dependencies, and results connected. It does not replace your AI agent or skill ecosystem.
Get started
RandComp Studio works with the AI tools you choose. Install the app, then operate the same local team from its desktop board or from an MCP-capable AI session. Claude Code, Codex, and Kimi Code are the bundled preview integrations, not the product boundary. Other configured runners are listed honestly when present, but their presence is not a claim of verified support.
Path 1
Requires: Apple silicon and macOS 11 or newer. Python and tmux are included.
RandCompStudio-0.1.1.dmg.Version, size, and SHA-256 are stamped into the landing page by the build; verify the hash shown there before opening the image.
Path 2
Requires: the RandComp Studio app, an AI client that supports a local MCP server, and randcomp on PATH. In the app, choose RandComp Studio → Install the randcomp command in PATH first.
claude mcp add -s user randcomp-studio -- randcomp mcp
The command above is the Claude Code example. -s user makes it available in every project; without it the server is registered only for the folder you ran it in. Other MCP clients register the same randcomp mcp process through their own local-server settings.
Your AI session can open tasks, hire roles, start agents, send work, and read results. The app shows the same board and terminals whenever you open it.
Registering also adds four RandComp Studio slash commands to that client.
This is a local MCP process over stdin and stdout—not a hosted server. RandComp Studio adds no account or API key. Your AI client still talks to its own vendor under that client’s settings.
The company folder holds roles, tasks, decisions, status, messages, and results as ordinary files. It is not necessarily the codebase where agents work. You choose project folders separately for each task.
If more than one configured runner is available, RandComp Studio asks which one should run coordinators. It checks whether the selected runner appears signed in, but never reads or stores the credential value and never signs in for you.
When creating a v2 project, you can keep the machine default, choose another available configured runner as the project default, and optionally override individual roles. The order is role override, project default, then machine default; changing a live agent in its inspector remains an explicit session override.
Five minutes
randcomp to open the company window.randcomp project create "Launch a small online store with a checkout" --runner kimi randcomp project list randcomp project ask PROJECT_ID "Add a gift-card page to the checkout" randcomp project show PROJECT_ID
Copy PROJECT_ID from randcomp project list. The ask is handed to the project's real coordinator session; planning the tasks is its judgment, not the CLI's. The same project commands work over SSH on the machine where the company lives.
The classic task-centric surface (randcomp task create and friends) is unchanged and still works for the company-level task board.
After registering the server, ask your AI session to create and manage the work through RandComp Studio rather than its own temporary subagents. The AI client chooses the MCP tools, while RandComp Studio owns the durable project, coordinator, helper agents, sessions, messages, and results underneath.
Use RandComp Studio to open a project for this work. Have the coordinator plan it and Developer implement it with QA reviewing. Keep the project and its helpers visible on the RandComp Studio board.
The MCP server publishes the project tools as v2_project_create, v2_project_list, v2_project_show, v2_project_ask, v2_project_finish, and v2_project_reopen, plus v2_task_*, v2_agent_*, and v2_result_* tools — alongside the classic company-level tools. Asking in your own words like above is still the main path. The four commands below are shortcuts for the sentences you would otherwise retype.
RandComp Studio publishes four prompts. Your client turns each one into a command you can pick at the start of a message. Claude Code 2.1.233 spells them like this, and lists every connected server’s commands under /mcp:
| Type | What it does |
|---|---|
/mcp__randcomp-studio__catch-me-up | Where the company stands: every task, who is on it, what is waiting on you, and what has gone quiet. Reads only. |
/mcp__randcomp-studio__what-came-out TASK_ID | What one task produced: what it was opened for, the outcome its coordinator wrote, and the complete path of every file. Reads only, long after the sessions are over. |
/mcp__randcomp-studio__start-work WHAT YOU WANT DONE | Opens a task for that sentence and lets its coordinator hire the roles the work needs. Starting agents spends money; leave the sentence off and you are asked for it. |
/mcp__randcomp-studio__check-on AGENT_ID | What one agent has been doing in its own words, and whether it is waiting on you. Reads only. |
The prompt names themselves are catch-me-up, what-came-out, start-work, and check-on. Other MCP clients offer the same four under their own spelling; check that client’s prompt or command list rather than assuming the form above.
Anything you type after the command is the command’s one value—a task ID, an agent ID, or the work you want done.
Each one returns text that says which RandComp Studio tools to call and how to read what comes back. Your session then makes those calls, under your client’s own approval settings, so nothing is opened, started, or stopped until you allow the tool call itself.
Core concepts
| Concept | What it means |
|---|---|
| Company | The durable folder containing your roles, tasks, decisions, messages, status, and produced artifacts. |
| Project folder | The codebase or working folder an agent operates in. It is selected per task and can be outside the company. |
| Project | The primary unit of work in the current app: one sentence about what you want, a coordinator that plans it into focused tasks, and the helpers hired to do them. Projects persist on disk and survive restarts. |
| Task | One focused piece of a project's plan, with its assigned helpers, live state, outcome, and files. The company-level classic task board also exists for work you dispatch directly. |
| Agent | One hired instance of a role on exactly one task. Two tasks using Developer get two different Developer agents. |
| Session | One running terminal for an agent. Sessions cost money; agents and their history remain when sessions stop. |
| Role | A reusable definition such as Developer, QA, or Market Analyst. Roles live in the helper library; they do not run by themselves. |
| Runner | The installed command-line AI agent that executes an agent. Claude Code, Codex, and Kimi Code are the bundled definitions in this preview, not the limit of the runner model — any CLI that runs in a terminal can be one. |
The role library has no live graph. Relationships and arrows only make sense inside one task, between the agent instances hired onto it.
Graphical interface
Run randcomp with nothing after it. It opens your company in a window of its own, served only to 127.0.0.1.
Start a project with one sentence, send requests to its coordinator, and watch the plan of focused tasks form — every task shows who is on it and what it produced.
Browse the reusable helper library, read role definitions, and import a definition you already have.
Open a helper's live session, read its terminal, change which AI tool it runs on, or stop the session without deleting the agent.
Review recorded company activity, choose light or dark appearance, pick your language, and replay the first-run tour.
A task’s state is derived from its agents rather than stored as a guess. Needs you means an agent recorded a blocker or request. Working means current work is active. Done means the task was finished. A quiet or unknown agent is explained with its cause instead of being silently called blocked.
Open an agent from its task, read its current terminal output, and send a line. “Open in a terminal” joins the actual tmux session; detach with Ctrl-B, then D, and the agent keeps working.
Command line
randcomp and randcomp-studio are the same program; randcomp is shorter to type. Every command names the thing first and the action after — randcomp task list, randcomp task results TASK_ID, randcomp task finish TASK_ID. The plural spellings (randcomp tasks ls, randcomp agents ID logs) still work and always will; the singular ones are what randcomp help teaches.
randcomp status randcomp task list randcomp agent list
status is the concise company summary: which program runs your agents and whether it is signed in, how many tasks and agents there are, and one line for each. randcomp task list says why each task is in the state it is in; randcomp agent list says what each agent is doing.
randcomp task list --company ~/Companies/acme randcomp --company ~/Companies/new-company
--company PATH works across the command surface. Naming a path that does not exist creates a company there. It does not change the project folder agents work in.
Reference
This reference follows the public parsers in the current source. Brackets mean optional input. Every command also accepts -h or --help; randcomp help prints the top-level map.
| Value | Where it comes from |
|---|---|
TASK_ID | The short slug beside a task in randcomp task list, or enough of its long name to match exactly one task. |
AGENT_ID | The ID in brackets after a role in randcomp agent list. A role name also works when only one agent has that role. |
RESULT_FILE_PATH | The complete path printed under “what it produced” by randcomp task results TASK_ID. |
ADDRESS | A hired agent ID or an unambiguous role name. |
--company PATH is accepted by the task, agent, role and status commands, and by the bare command that opens the window. It selects the folder holding roles/ and coordination/; it does not select an agent’s project folder. The remembered first-run company is the default. A named path that does not exist is initialized as a company. On role commands the flag may appear before or after the verb.
randcomp mcp [--company PATH]
Speak Model Context Protocol over stdin and stdout so a local MCP client can read and drive the company. Register it with claude mcp add -s user randcomp-studio -- randcomp mcp rather than running it by hand. It publishes tools the client calls and the four prompts the client shows as slash commands. --company selects a company other than the remembered default. There is no network listener, hosted service, RandComp Studio account, or API key.
The project surface is the current app's primary model: a project holds one sentence of intent, a coordinator, and the plan of focused tasks the coordinator made. The commands below are the complete project grammar; every one also accepts --company PATH.
randcomp project create TEXT... [--title WORDS] [--runner NAME]
Open a project for that sentence. --runner sets the project's default AI tool (for example kimi, claude, or codex); otherwise the machine default is used.
randcomp project list [--json]
Every project, its state, and how many tasks it holds.
randcomp project show PROJECT_ID
One project's detail: its request history, the coordinator's state, and its plan.
randcomp project ask PROJECT_ID TEXT...
Write a request against the project. Its coordinator session is woken — or hired and launched — and reads it; planning the tasks is the coordinator's own judgment.
randcomp project finish PROJECT_ID randcomp project reopen PROJECT_ID
finish closes the project and stops its agents; reopen opens it again without starting anything.
Inside a project, tasks and agents answer to randcomp task create --project PROJECT_ID, randcomp task list --project PROJECT_ID, and randcomp agent list --project PROJECT_ID; the singular verbs with a project flag are the v2 grammar, while their plural legacy spellings keep their classic meaning.
randcomp task create TEXT... [OPTIONS]
Open a task, start its coordinator, and let the coordinator hire the roles it needs.
--name WORDS sets the display name and the basis of the short task slug. The request text is the default.--in PATH sets the project folder every agent opens. The last project folder used is the default.--only ROLE,ROLE limits which roles the coordinator may consider and remembers that narrowing. --only all clears it.--with-role ROLE hires one role you chose instead of asking the coordinator to choose it.--let-it-work-without-asking requests the runner’s unattended permission mode. This lowers an approval boundary; randcomp role list prints what the runner permits.--anyway confirms the new spend when sessions are already running. Without it, RandComp Studio reports what is running and stops.randcomp task list [--json] [--company PATH]
Print the company org chart: every task, derived state, agent, and ready-to-run command. --json returns the same listing as structured JSON.
randcomp task results TASK_ID [--json] [--company PATH]
Show what was requested, the coordinator’s outcome, participants, and complete paths of produced files. The task may be omitted when it can be resolved interactively. It lists files rather than printing their contents. --json produces structured output.
randcomp task show RESULT_FILE_PATH [--company PATH]
Print one produced document whole. This is the same command as the one above: anything containing a directory separator is read as a path to a produced file, and anything else as the name of a task. Use the exact path printed under “what it produced”.
randcomp task finish TASK_ID [--yes] [--company PATH]
Close a task and stop every agent session on it. In a terminal it names the sessions and asks first. --yes answers in advance; non-interactive scripts are never prompted. Agents and history remain.
randcomp task reopen TASK_ID [--company PATH]
Open a finished task again. It deliberately starts no sessions; list the old agents and run randcomp agent start AGENT_ID only for those you want working.
randcomp agent list TASK_ID [--json] [--company PATH] randcomp agent list [--json] [--company PATH]
List the agents on one task, or every agent in the company when no task is named. --json returns structured output.
randcomp agent logs AGENT_ID [--company PATH]
Read the agent’s words: full live scrollback while it runs, or its saved conversation after it stops. This is not the reusable role definition.
randcomp agent send AGENT_ID TEXT... [--company PATH]
Write a line to an agent. It enters the live session, or waits in the agent’s inbox when no session is running.
randcomp agent attach AGENT_ID [--print-the-command] [--company PATH]
Join the tmux session in this terminal; detach with Ctrl-B, then D. --print-the-command prints the join command without running it, for another terminal or script.
randcomp agent start AGENT_ID [--company PATH] randcomp agent stop AGENT_ID [--company PATH]
start gives the durable agent a session, resuming its identity and history. stop ends only that session; the agent stays and can start again.
randcomp role add ROLE [OPTIONS]
Put one of this company’s roles on a task. Hiring records the instance; it does not necessarily launch it. role hire is the older spelling.
--assignment WORDS... records this instance’s one piece of work; it may be added later.--in PATH sets the project folder the agent opens. The company folder is the default. The legacy hidden spelling --project PATH is equivalent.--task SLUG binds the agent to one task’s coordination-directory slug. Omit it only for genuinely cross-task work.--because WORDS records why the task needs this role.--runner NAME chooses the runner; otherwise the installed configured default is used.randcomp role assign ADDRESS --assignment WORDS... [--continue] [--company PATH]
Change an agent’s assignment. A different piece of work is refused because one agent session owns one assignment. --continue explicitly says this is the same work described more clearly.
randcomp role outcome --task SLUG [WORDS...] [--company PATH]
Record the task’s concise outcome, produced paths, conclusions, and remaining work. Supplying no outcome words clears an incorrect outcome.
randcomp role list [--all] [--company PATH]
List the hired roster and what is running. --all includes retired hires. role roster is equivalent.
randcomp role retire ADDRESS [--company PATH]
Stop listing a hire as active. Its recorded history is retained.
randcomp role import PATH [OPTIONS]
Translate an existing skill, agent, GPT export, AGENTS.md, or Markdown definition into a RandComp Studio role package. PATH may be a file, a containing directory, or - for stdin.
--as NAME overrides the inferred role name.--add, it writes nothing and prints the proposed package for review.--add copies the translation into role-library/<name>/ and generates roles/<NAME>.md. It never edits the source or overwrites an existing role.--anyway permits writing despite non-fatal missing information; it cannot override a missing name, missing mission, or overwrite refusal.randcomp role runners [--company PATH]
List every configured runner, whether it is installed and signed in, and which runner is the default.
randcomp role coordinator [--use NAME | --default] [--company PATH]
With no option, show the runner used for new coordinators. --use remembers a new choice. --default forgets that choice and returns to the runner table’s default. Existing coordinator sessions are unchanged.
randcomp role runs-on ADDRESS [--use NAME] [--wait SECONDS] [--company PATH]
Show one agent’s runner. --use moves it to another runner. If it is live, RandComp Studio requests and verifies a handover before replacing anything; --wait sets the handover deadline, using the runtime default when omitted.
randcomp role launch ADDRESS [--let-it-work-without-asking] [--company PATH]
Give a hired agent a session. The unattended flag is an explicit safety-boundary reduction and is refused if that runner has no defined unattended mode.
randcomp role stop ADDRESS [--company PATH] randcomp role attach ADDRESS [--company PATH]
stop ends the session but keeps the hire. Role-level attach prints the command that joins the session; the noun-first agent attach command joins it directly.
randcomp role replace ADDRESS [--wait SECONDS] [--let-it-work-without-asking] [--company PATH]
Ask a live agent for a handover, verify it, retire the old session, and start a fresh continuation. If the handover misses the timeout, the old session is left exactly as it was.
randcomp role at-once [HOW_MANY] [--company PATH]
Show or set how many specialist agents on each task may run simultaneously. Extra hires wait their turn. The task coordinator is not counted. The old at-most command was removed and only explains its replacement.
randcomp role check ADDRESS [--company PATH] randcomp role history ADDRESS [--company PATH]
check takes everything waiting from an agent’s inbox. history shows every session that hire has had and the succession between sessions.
randcomp role say ADDRESS TEXT... [--about TASK_ID] [--company PATH]
Send a founder-authored message. --about disambiguates the task when writing to the cross-task coordinator.
randcomp role send --to ADDRESS --from NAME [--as-founder] TEXT... [--company PATH]
Send a message from one role to another. --from records the truthful sender; --as-founder explicitly marks the message as founder-authored.
randcomp role route [--company PATH]
Deliver everything currently waiting in the role outbox.
randcomp role read ADDRESS [--lines N] [--company PATH]
Read the full live scrollback or saved conversation. --lines N limits only live scrollback; completed conversations are always shown whole.
randcomp role inbox [ADDRESS] [--company PATH]
Show unread messages for one recipient, or for every recipient when the address is omitted.
randcomp status [--json] [--company PATH]
Print the selected runner and sign-in state, task and agent counts, then one concise line for each. --json returns structured output.
randcomp [--company PATH] [--no-model]
With nothing after it, open your company in a window of its own, served only to 127.0.0.1. --no-model disables the optional local-model paragraph.
randcomp help randcomp COMMAND --help
Print the complete command map, or the parser help for one command.
randcomp COMMAND --no-color
Every command paints four things when — and only when — a person is reading it: the state a piece of work is in, the words you copy off the screen, the headings, and the context lines it dims to make the rest findable. Piped, redirected, or read by an agent, the output is plain text byte for byte. --no-color works on every command; NO_COLOR and FORCE_COLOR are honoured as well.
The grammar above is the one to learn. Every spelling this tool has ever answered to still runs, unchanged, so nothing already written down breaks:
task create, do, dispatch | tasks new |
task list | tasks ls |
task results, results | tasks TASK_ID |
task show, show | tasks RESULT_FILE_PATH |
task finish, finish, reopen | tasks TASK_ID finish / reopen |
agent list | tasks TASK_ID agents |
agent logs/send/attach/start/stop, read, say, attach, start, stop | agents AGENT_ID logs and the rest |
role library, roles | Folded into role list and role import |
role add | role hire |
app, ui | Bare randcomp |
inbox, handoff, todo add/note/done | No longer part of the taught surface; still runnable |
Execution
A role is the interface; a runner is the installed program that executes it. Two agents of one role may use different runners.
randcomp role runners randcomp role coordinator --use NAME randcomp role runs-on AGENT_ID --use NAME randcomp role at-once NUMBER
coordinator --use changes the runner for coordinators started from then on. runs-on moves one agent to a runner. at-once controls how many specialist agents on each task run simultaneously; extra agents remain hired and wait their turn.
RandComp Studio ships its first runner definitions for Claude Code, Codex CLI, and Kimi Code. They are initial integrations, not the product definition. Advanced users can add or override runners in ~/.config/mission-control/runners.json without modifying the product, and additional built-in runners are the next compatibility step.
RandComp Studio is not a replacement marketplace. Its importer accepts a role definition you already have—such as an Agent Skill, Claude agent or skill, exported GPT, or plain Markdown—and translates it into the local role-package contract.
randcomp role import ROLE_SOURCE_PATH randcomp role import ROLE_SOURCE_PATH --add
The first command is a review: it prints what was understood, what the role would become, and whether its matching rules can actually select it. Nothing is written without --add. The source path is read-only; the approved translation is copied into your company’s role-library/.
Local by design
127.0.0.1.~/.config/mission-control by default. Set MISSION_CONTROL_HOME to override it.Agents read and modify the project folder through the command-line AI agent you selected. Its approval and sandbox settings determine what the agent may do.
Sessions spend
Hiring an agent writes a durable record. Starting its session is the step that can spend money. RandComp Studio keeps those concepts separate.
Common problems
randcomp: command not foundAdd ~/.local/bin to your PATH. The installer prints the exact line for your shell.
export PATH="$HOME/.local/bin:$PATH"
This applies to a source install only — the application carries its own Python. From source, RandComp Studio requires Python 3.11 because it reads TOML runner configuration; on macOS, brew install python supplies a current version. You can also run:
MISSION_CONTROL_PYTHON=/path/to/python3 ./install.sh
The application carries its own tmux, so there is nothing to install for that. What it cannot carry is your command-line AI agent: confirm one is on your PATH and signed in with its own command — randcomp status says which it found and whether it is signed in. If you installed from source rather than the application, tmux does have to be on the machine. Then check:
randcomp status randcomp role runners
The remembered company does not change with your current directory. Name another one deliberately with --company PATH.
Read the exact cause and its transcript before restarting it:
randcomp agent logs AGENT_ID randcomp agent attach AGENT_ID
Housekeeping
The installed commands intentionally point to that folder. After moving it, run ./install.sh again from the new location.
rm ~/.local/bin/randcomp rm ~/.local/bin/randcomp-studio
Then remove the unpacked product folder. Your company folder belongs to you and is left untouched.