Codeway documentation

Codeway is a coding agent that runs in your terminal and as a chat on the web — the same Agens Pilot model, the same account, the same monthly allowance.

Overview

In the terminal, Codeway is a full-screen agent: it reads your repository, runs commands in a sandbox, edits files, searches the web, and delegates work to sub-agents — with two safety knobs (a sandbox and an approval policy) you control per session. On the web, it is a chat that sees and makes images and can search and read the web, with no local files or shell.

Everything a session does is written to an append-only log, so any session can be replayed exactly. The model is Agens Pilot: a 1M-token context, native 廣東話, text and vision.

Install

The terminal installs from npm. It carries a prebuilt binary for your platform, so there is no compiler to run.

$ npm install -g codeway

Requirements: Node 20 or newer, on macOS or Linux (Apple Silicon or Intel). Then check it:

$ codeway --version

Other ways to install

From source (for contributors). With a Rust toolchain and Node 20+:

$ cargo install --path crates/cw-cli

Homebrew is on the way. Until a public tap is published, npm is the supported install for everyone; the Homebrew formula in the repository builds from source and is for maintainers.

Sign in

Every session needs a Blockway account. Signing in opens your browser and stores a token for this terminal — the same account you use on the web app.

$ codeway login

codeway login --no-browser — prints a link and a code to open elsewhere. For SSH.
codeway login --token <token> — signs in without a browser. For CI and scripts.
codeway whoami — who this terminal is signed in as, and what is left of the allowance.
codeway logout — forget the stored token.

Don't have an account yet? Create one on the web app — it is the same login.

Quickstart

Run it in a project directory:

$ cd my-project
$ codeway

Type what you want done and press Enter. Codeway plans, runs commands, and edits files, asking before anything it is not allowed to do on its own. Ctrl-C stops the current turn; type /help for the keys and slash-commands.

One task, no terminal

For scripts and CI, run a single task and exit:

$ codeway exec "add a test for the parser and make it pass"

--quiet prints only the final answer; --json emits one event per line.
--resume latest continues the most recent session.
--goal treats the prompt as a standing goal: Codeway keeps taking turns until the model says it is done or a budget runs out.

The web app

Open the web app, sign in, and you have the same model in the browser. It has no access to your files or shell — it is a chat that:

sees images you drop or paste, and answers about them;
generates images inline — ask for a picture, an illustration, a concept;
searches and reads the web.

Your allowance is shared: a turn on the web and a turn in the terminal draw from the same monthly balance.

Commands

Command	What it does
`codeway`	The interactive terminal agent.
`codeway exec <prompt>`	Run one task without a terminal, then exit.
`codeway login` / `logout`	Sign this terminal in or out of its account.
`codeway whoami`	Account and remaining allowance.
`codeway update`	Update to the newest published release.
`codeway init`	Write this project's `CODEWAY.md` by reading the repo.
`codeway skills`	List the skills a session here would offer.
`codeway sessions <action>`	Inspect recorded sessions (see below).
`codeway config <action>`	Inspect and change configuration.
`codeway serve --http <addr>`	Serve the agent over HTTP with a simple web UI.
`codeway acp`	Speak the Agent Client Protocol, so an editor can drive it.

Sessions

Every session is recorded and can be replayed. To look back:

codeway sessions list — recent sessions, newest first.
codeway sessions show <id> — the derived history (latest works too; --thinking includes reasoning).
codeway sessions stats <id> — what it did, and what it cost.

Updating

An npm install checks for a newer release in the background, at most once a day, and updates itself quietly. To update now:

$ codeway update

Set CODEWAY_NO_UPDATE=1 to turn the background check off.

Configuration

Settings live in ~/.codeway/config.toml, with a per-project .codeway/config.toml layered on top. To see and change them:

codeway config paths — where Codeway reads and writes things.
codeway config dump — the effective settings, annotated with where each came from.
codeway config fields — every setting and what it means.
codeway config set <key> <value> — write one setting.

Using your own model

The account is always Blockway — that is what signs the terminal in. The model, though, is yours to point wherever you like. Set the endpoint and which environment variable holds its key:

$ codeway config set model.base_url http://localhost:11434/v1
$ codeway config set model.model my-model
$ codeway config set model.api_key_env MY_KEY

For a hosted Blockway endpoint the key comes from your login; for any other endpoint it is read from the environment variable you name (set it to an empty string for a server that takes no key).

Safety

Two knobs, kept separate, decide what a session may do:

The sandbox confines what commands can read, write, and reach on the network. On the web app there is no shell at all.
The approval policy decides what runs on its own and what stops to ask you first. Presets range from asking about everything to full-auto.

A plugin can only do what a capability grants it, so installing one never quietly widens what a session can reach.

← Back to Codeway