Roko PlatformDocs

Getting started

Foundational tooling

You need a coding agent on your own computer to use Roko Platform effectively. This page installs git, Node.js and an agent, and teaches you to drive the agent from a terminal.

Coding agents

A coding agent is a program you talk to in a terminal. You describe what you want. The agent reads, changes, and checks files on your computer, then tells you what it did.

The loop

Every request goes through the same five steps. Click through an example:

Steps 2 to 4 repeat as needed

Step 1 of 5

You prompt. Describe the result you want in plain language. You do not need to name files.

>_your-project · coding agent
> Add a dark mode toggle to the settings page.
Select a step, or press Next step. The transcript builds up as the agent works.

The agent reads before it acts and checks after. It also asks before it edits a file or runs a command. You can allow the action, deny it, or set a rule. See Permissions.

Where agents fall short

These limits are part of how agents work. Know them before you rely on one.

LimitWhat it means for you
It cannot read your mindIt knows only the files in its folder and what you tell it. When you leave something out, it guesses.
It is confident when it is wrongA wrong answer sounds as certain as a right one.
It cannot judge what a test cannot checkIt can run tests and builds. It cannot tell whether the wording, the design, or the task itself is right. You judge that.
It drifts on vague, large requestsGive it one clear task at a time. A request for everything gets you a large pile of work to read.
It does not know your team's rulesIt does not know unwritten conventions or past decisions. Tell it, or it may undo them.

Agents in Roko Platform

You need a coding agent on your own computer to use the platform effectively. Your agent drafts change requests, seeds the working model, builds prototypes and builds implementations. Run Claude Code, Codex CLI or Copilot CLI, and connect it to the platform. Install the tools covers the install, and Connect over MCP covers the connection.

The platform also runs its own agents to build implementations and to run on a schedule. They do not replace your local agent.

The terminal

A terminal is a window where you type commands. The text before your cursor is the prompt. Type a command after it and press Return.

Terminal
you@laptop Documents % 1pwd2
/Users/you/Documents3
you@laptop Documents % ls
Notes.txt   roko-practice
you@laptop Documents % 
  1. 1The prompt. The terminal waits here.
  2. 2A command. Type it, then press Return.
  3. 3The output. What the command printed.
The same idea in PowerShell on Windows, where the prompt reads PS C:\Users\you>.

Open a terminal

Press Command and Space together, type Terminal, and press Return.

Common commands

Run them one line at a time. Text after a # is a comment, and the terminal ignores it.

pwd                  # which folder am I in
ls                   # what is in this folder
cd Documents         # go into a folder
cd ..                # go back up one folder
mkdir roko-practice  # make a folder
open .               # open this folder in Finder

Common errors

What you seeWhat it means
command not foundThe program is not installed, or the name is misspelled. Check the spelling first. After an install, open a new terminal and try again.
permission deniedYou cannot change that file or folder. Usually you are in the wrong folder.
Nothing happensSome commands take minutes and print nothing. To stop a command, press Control and C.

Install the tools

Run the check after every step. Most later problems come from an install that did not finish.

The account you need

Your agent needs an account. Set it up before you install anything.

Claude Code needs a Claude account on a paid plan, or an Anthropic API key.

Install git

git records changes to files. You rarely use it directly, but every agent needs it. macOS and most Linux systems already have it. Check first:

git --version

If it prints a version number, skip to Identify yourself to git. If it prints command not found, install git:

xcode-select --install

A window opens. Choose Install and wait for it to finish.

Then run git --version again.

Identify yourself to git

git saves a name and an email with every change, including changes an agent makes for you. Replace the example values with your own:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Install Node.js

Codex CLI and GitHub Copilot CLI install through npm, which comes with Node.js. Claude Code does not need it: skip to Install the agent.

brew install node

If the terminal says brew: command not found, install Homebrew first, then run the command again:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Check the version:

node --version

It must print 22 or higher. If it is older, install the current release from nodejs.org and check again.

Install the agent

curl -fsSL https://claude.ai/install.sh | bash

Check it:

claude --version

Sign in to the agent

Run this command:

claude

Type /login and finish the sign-in in the browser window that opens.

To confirm, ask the agent a short question, such as which folder it is in. If it answers, you are signed in.

Check the installation

The installation is complete when all four checks pass:

  • git --version prints a version.
  • node --version prints 22 or higher, if your agent needs Node.js.
  • The agent prints its own version.
  • The agent answers a question you asked it.

Next, connect the agent to Roko Platform.

Drive an agent

Where to start it

The agent works in the folder where you start it, and it can read and change everything inside. To try the agent out, make a practice folder:

mkdir roko-practice
cd roko-practice

For real work, start the agent in the top folder of the project so it can see all of it.

Write a brief

Brief the agent as you would brief a teammate. A good brief is specific, not long. Say what you want, where, any limits, and how to confirm it worked.

Too vague

Make the onboarding better.

The agent has to guess where, what, and when it is done.

Briefed

The signup form asks for a company name before it explains why.1Move that field to the second step,2keep it optional,3and tell me which files you changed.4

  1. 1Where, and the problem
  2. 2What you want
  3. 3The limits
  4. 4How to confirm it
The brief names where, what, the limits, and how to confirm it worked.
  • Ask for one task at a time.
  • Say what it must not change.
  • Paste the exact error text instead of describing it.
  • For a large change, ask for a plan before it starts.
  • If it gets something wrong, correct it in the same session. You rarely need to start over.

Pick a model

Type /model in the session to pick a model.

Start with the largest model you have. Switch to a smaller one when small tasks feel slow.

Set the reasoning effort

Open /config and set the reasoning effort. Raise it for work that needs planning. Lower it for small edits. More reasoning gives slower, more expensive, and usually better answers.

Permissions

Claude Code asks before it edits a file or runs a command. Type /permissions to see and change the rules.

A flag turns the questions off completely:

claude --dangerously-skip-permissions

Stop and quit

The three agents use the same keys.

ToDo this
Stop the current taskPress Esc. The agent stops and waits for you. The session keeps the conversation.
End the sessionPress Control and D, or type /exit. In Codex CLI, type /quit. Your files stay as they are.
Force quitIf the agent does not respond, press Control and C twice.

If you stop the agent while it edits files, a change can be half done. Ask the agent what state it left, or run git status.

When this page and your agent disagree

These tools change often. Type /help in a session to see what your version supports.