Five minutes
Run your first project
From the UI
- Run
randcomp to open the company window.
- Choose Start a project and describe what you want in one sentence.
- RandComp Studio opens the project and tells its coordinator what you asked.
- Your coordinator turns the sentence into a plan of focused tasks and hires the helpers to do them.
- Watch each task: who is on it, what it produced, and what needs you. Send the next request from the composer whenever you want.
From the CLI
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.
Tasks and helpers live inside a project: randcomp task create --project PROJECT_ID "...", randcomp task list --project PROJECT_ID, randcomp agent list --project PROJECT_ID, randcomp result list --project PROJECT_ID. The older spellings (randcomp tasks ls, randcomp tasks new, randcomp agents, randcomp finish ID) still run exactly as before and print one line naming what they are called now; see Older spellings.
From an AI session over MCP
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 24 tools in four families, named after the model: a project holds tasks, a task has helpers on it, and the tasks produce results.
| Family | Tools |
|---|
project_* | project_create, project_list, project_show, project_ask, project_finish, project_reopen, project_outcome_update |
task_* | task_create, task_list, task_show, task_assign, task_depend, task_result_add, task_finish, task_reopen |
helper_* | helper_list, helper_logs, helper_send, helper_start, helper_stop, helper_attach |
result_* | result_list, result_show |
role_library | role_library |
The two that spend money say so in their own descriptions, and your client asks before calling them: task_assign and helper_start start a real session, and task_create is marked as spending because its older company-level form dispatches a coordinator. Everything else reads or records.
The earlier names still answer, though they are no longer listed: every v2_* tool (v2_project_create, v2_agent_list and the rest; agent_id is still accepted wherever helper_id is) and the older company tools (task_results, task_delete, agent_*, role_add). task_list, task_create and task_finish are the one place two meanings share a name: call them with project_id (or task_id for task_finish) and you get the project model; without it you get the older company-level call, which needs a company chosen. Each tool’s description is in English and Chinese.
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.
Slash commands
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.
A command hands your session a starting point, not an answer.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.
Reference
Complete CLI 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.
Values and shared behavior
| Value | Where it comes from |
|---|
PROJECT_ID | The id printed by randcomp project list, such as project-47e1a136b134. |
TASK_ID | The id printed by randcomp task list --project PROJECT_ID, such as task-0c1d69cc7b85. In the classic company commands it is the short slug beside a task in the older randcomp tasks ls. |
AGENT_ID | The id printed by randcomp agent list. In the classic commands a role name also works when only one agent has that role. |
RESULT_ID | The id printed by randcomp result list --project PROJECT_ID or shown on randcomp task show TASK_ID. |
RESULT_FILE_PATH | The complete path printed under “what it produced” by the classic randcomp tasks TASK_ID. In the project model use randcomp result show RESULT_ID. |
ADDRESS | A hired agent ID or an unambiguous role name. |
--company PATH is accepted by the classic company commands, role, status and 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. The project, task --project, agent --project and result commands act on the project store under ~/.config/mission-control (or MISSION_CONTROL_HOME) and do not take it.
MCP server
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.
Projects
The project surface is the primary model: a project holds one sentence of intent, a coordinator, and the plan of focused tasks the coordinator made. Each command below has an MCP twin of the same name (project create is project_create). Every command prints JSON and none of them take --company.
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
Every project, its state, and the tasks it holds. Prints JSON.
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 outcome PROJECT_ID TEXT...
Rewrite the project’s one-line outcome, for example to what was actually delivered.
randcomp project finish PROJECT_ID
randcomp project reopen PROJECT_ID
finish marks the project completed and reopen opens it again; neither starts anything.
Tasks
Tasks, helpers and results live inside a project. The commands below have MCP twins (task create is task_create, agent list is helper_list) and print JSON.
randcomp task create --project PROJECT_ID TEXT...
Add a task to a project. It costs nothing by itself: no helper is hired until you assign one.
randcomp task list --project PROJECT_ID
randcomp task show TASK_ID
Every active task in a project, or one task with its state, dependencies, helpers and results.
randcomp task assign TASK_ID --role ROLE --brief TEXT [--let-it-work-without-asking]
Put a real helper on a task. This starts a real, paid session. --let-it-work-without-asking requests the runner’s unattended permission mode and lowers an approval boundary.
randcomp task depend TASK_ID --on OTHER_TASK_ID
The task cannot start before the other one, in the same project, finishes.
randcomp task result-add TASK_ID --kind KIND --path-or-url WHERE
Record one result: a file path, or a live URL (kind website).
randcomp task finish TASK_ID
randcomp task reopen TASK_ID
finish marks a task done; its helpers stay on the roster with their history. reopen moves it back to active.
Results
randcomp result list --project PROJECT_ID [--task TASK_ID]
Everything the project’s tasks produced, or one task’s.
randcomp result show RESULT_ID
One result, printed whole when it is a local file.
Classic company tasks
Without --project, task create, task list, task results, task show RESULT_FILE_PATH, task finish and task reopen are the company-level task board that existed before projects. They keep their old behaviour, need a company, and print a line naming the project command that replaced them. Projects and classic tasks are separate data: a classic task does not appear in project list.
randcomp task create TEXT... [OPTIONS]
Open a classic 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.
Agents
An agent is a helper working on one task. Its MCP twins are the helper_* tools.
randcomp agent list [--project PROJECT_ID] [--task TASK_ID]
List every helper, or narrow to one project or one task. Prints JSON.
randcomp agent list TASK_ID [--json] [--company PATH]
The classic form: the agents on one classic task.
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.
Role library and hiring
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.- Without
--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.
Role sessions and runners
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.
Role messages
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.
Company status and the window
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.
Colour
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.
Older spellings
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. Each one prints a single line on stderr naming what it is called now (for example `tasks ls` is the older name for `project list`. It still works, unchanged.) and then does what it always did. --help prints no hint, and commands with no new name (tasks ID delete, todo, note, done, status) print none. Hints follow MCTL_LANG=en|zh, else your locale.
An older spelling is not rerouted: it reads and writes the classic company data, not the project store, so tasks new does not create something project list shows.
project create | tasks new, do, dispatch |
project list | tasks ls, task list (no --project) |
project show, result list | tasks TASK_ID, task results, results |
result show | tasks RESULT_FILE_PATH, task show RESULT_FILE_PATH, show |
project finish / reopen | tasks TASK_ID finish / reopen, finish, reopen |
agent list | tasks TASK_ID agents, agents |
agent logs/send/attach/start/stop | agents AGENT_ID logs and the rest, read, say, talk, attach, start, stop |
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 |