Getting started

Install

Install the extension from the Visual Studio Code Marketplace. Building from source stays available for development.

Install from the Marketplace

The Marketplace is the main way to install Origami Coder. Search for Origami Coder in the VS Code Extensions view, or install by identifier: OrigamiLabs.origamicoder. The extension bundles the engine and its search tool for your platform, so one install gives you the whole product.

Origami Coder is pre-release. The Marketplace listing goes live with the first public build.

Build from source

The engine and the extension build independently. A source install needs both.

Requirements

• Bun 1.3.14. The repository declares it as its package manager.
• VS Code ^1.106.0 for the extension.

Build the engine

The engine build script writes a binary for the current platform. Use --single to build only that one target.

bun install
cd packages/engine
bun run script/build.ts --single

Other flags of the build script are --baseline, --skip-install, --sourcemaps and --skip-embed-web-ui.

The command name is origami. The package declares the launcher at bin/origami.

Build the extension

cd packages/vscode
npm run build      # node esbuild.js
npm run typecheck  # tsc for src and webview
npm run package    # vsce package --no-dependencies

npm run package writes a .vsix file. Install that file in VS Code. The extension identifier is OrigamiLabs.origamicoder.

Run the type check. The unit tests do not check types. Vitest removes types without checking them, so code that cannot compile can still have a green test run.

Where files are kept

The command origami debug paths prints these paths.

Remove the program

origami uninstall removes the program and its files. It accepts --keep-config, --keep-data, --dry-run and --force.

Reference

Configuration

One JSON file holds the engine configuration. The terminal UI keeps its own file.

File names

The engine reads origami.json and origami.jsonc. The global directory also accepts the older name config.json.

Project files are found by a walk up the directory tree from the working directory to the worktree root. The file closest to the working directory wins.

Order of merge

Later sources overwrite earlier sources.

1. The global directory: config.json, then origami.json, then origami.jsonc.
2. The file named by ORIGAMI_CONFIG.
3. Project origami.jsonc and origami.json, walking up.
4. Each .origami directory, and ORIGAMI_CONFIG_DIR if it is set.
5. Inline JSON in ORIGAMI_CONFIG_CONTENT.
6. The system-managed directory.

The system-managed directory is /Library/Application Support/origami on macOS, %ProgramData%\origami on Windows, and /etc/origami elsewhere.

Unknown keys are an error

The parser accepts JSONC with trailing commas. An unknown key at the top level stops the load with the message Unrecognized key(s).

The keys theme, keybinds and tui are removed from origami.json on load. They belong in tui.json.

Values from the environment and from files

Before the parse, the loader replaces two patterns in the text.

Top-level keys

Deprecated keys

These keys still load. Use the replacement instead.

• autoshare — use share.
• reference — use references.
• mode — use agent.
• tools — use permission.
• layout — has no effect.

Experimental options

Environment variables

A variable is true when its value is true or 1.

The command origami debug config prints the resolved configuration.

Usage

VS Code

The extension is the main surface. It holds the chat view, the dashboard and the Folds board.

Identity

• Name: origamicoder. Publisher: OrigamiLabs. Display name: Origami Coder.
• Required editor: VS Code ^1.106.0.
• The extension starts on the onStartupFinished event.

Commands

origami.init shows the chat view and runs /firstfold. origami.openAgentManager opens the Folds board, which runs parallel agents in separate git worktrees.

Key bindings

Settings

Workflow settings

Every workflow option is off by default.

The context meter

The extension counts the tokens of each turn and keeps a total per session. It records prefill (input), read (cache read), write (output), the turn count, the window occupancy and the window size.

The fill bar has three bands: 80 percent or more is high, 60 percent or more is middle, below that is low. A reported value of zero means "not known" and keeps the earlier value, because a local server often reports zero for the window size.

Chat commands in VS Code

The extension answers four slash commands itself. They never reach the engine.

Usage

First fold

/firstfold turns an empty folder into a workspace. It is a command of the VS Code extension.

What it writes

The wizard shows a live checklist while it works. Each step is paced. Existing files are skipped, never overwritten, so you can run it again safely.

1. Scan the workspaceIt reads package.json scripts and marker files such as Cargo.toml, pyproject.toml, requirements.txt and go.mod to find the build, test and lint commands.
2. Write AGENTS.mdHouse rules for the agent, plus a "Build and test" section from the scan.
3. Create foldersprojects/, scripts/ and crons/.
4. Seed the wikiwiki/pages/ and a wiki/index.md primer.
5. Create HANDOFF.mdA rolling session log with an anchor line that marks where new blocks go.
6. Seed commands and skills.origami/command/example.md and one .origami/skills/<name>/SKILL.md per default skill.
7. Connect a modelA provider picker writes the provider block into the global configuration file.

Run /firstfold model to repeat only the model step.

Reload the window after a first fold. The engine reads the configuration and scans .origami/command and .origami/skills once, when it starts.

The default skills

These skills are written into .origami/skills/<name>/SKILL.md.

• wrap, example-skill
• grill-me, to-spec, to-tickets, triage, tdd, diagnosing-bugs, code-review, wayfinder, handoff

The wrap skill

/wrap closes a session. It is a skill file, not engine code. It becomes a slash command because the engine registers every skill as a command.

The skill does two linked jobs in one pass.

1. Insert a block in HANDOFF.md, directly below the anchor line. The block holds a dated heading, a done: line, a next: line and a wiki: link.
2. Write the depth into wiki/pages/<page-name>.md: one topic per page, kebab-case, flat, with tags frontmatter and at least one link to another page.

A workspace that never ran /firstfold has no wrap skill. Copy the file, or write your own.

Usage

Terminal UI

Run origami with no command to open the terminal interface.

Start it

origami                 # start in the current directory
origami ./my-project    # start in a directory
origami -c              # continue the last session
origami -m lmstudio/qwen3-coder

The terminal interface is a SolidJS application drawn by OpenTUI.

Its own configuration file

Terminal settings live in tui.json or tui.jsonc, not in origami.json. The search order is the global directory, then ORIGAMI_TUI_CONFIG, then project files walking up, then each .origami directory.

Slash commands in the terminal

These commands belong to the terminal interface. They do not reach the engine.

The terminal autocomplete hides slash commands that come from skills. The VS Code palette shows them.

Side panel

The side panel holds a context readout, an MCP list, a language-server list, the todo list and the file list.

Usage

Command line

The binary is origami. With no command it opens the terminal interface.

Global options

origami completion writes a shell completion script.

Commands

Options of the terminal command

Options of run

Sub-commands

Diagnostics

origami debug holds the diagnostic commands: config, paths, info, startup, skill, scrap, agent <name>, snapshot, file, rg, lsp and v2 (the built-in catalog and plugins).

Usage

Server

The engine runs headless. Other programs then drive it over HTTP.

Start a server

origami serve
origami serve --port 4096 --hostname 127.0.0.1
origami web

serve prints the address it listens on. web also opens the web interface.

Network options

These options belong to origami, acp, serve and web. They can also come from the server block of the configuration.

Set a password. The server prints a warning when ORIGAMI_SERVER_PASSWORD is not set, because the server is then unsecured. --mdns binds to every interface.

Attach to a server

origami attach http://localhost:4096
origami run --attach http://localhost:4096 "list the open tickets"

The HTTP interface

The server is an Effect HTTP application. It publishes an OpenAPI document, and it accepts WebSocket connections.

The route groups are config, control, control-plane, event, experimental, file, global, instance, mcp, metadata, permission, project, project-copy, provider, pty, query, question, session, sync, tui and workspace.

A generated OpenAPI document is kept in the repository.

Configure

Models and providers

A model is named provider/model. A provider block describes where the model lives.

Choose a model

The name is split at the first slash only. A model identifier may therefore contain slashes, as in lmstudio/qwen/qwen3-coder-30b.

origami models lists every model as provider/model.

A provider block

{
  "provider": {
    "lmstudio": {
      "name": "LM Studio",
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "http://127.0.0.1:1234/v1" },
      "models": { "qwen3-coder-30b": { "name": "Qwen3 Coder 30B" } }
    }
  },
  "model": "lmstudio/qwen3-coder-30b"
}

The keys of a provider block are api, name, env, id, npm, whitelist, blacklist, options and models.

Provider options

Model overrides

Each entry of models may set id, name, family, release_date, attachment, reasoning, temperature, tool_call, interleaved, cost, limit, modalities, experimental, status, options, headers, variants and a nested provider.

limit holds context and output. modalities holds input and output lists over text, audio, image, video and pdf.

A model that the model database does not know keeps tool_call true and every other capability false. Set "tool_call": false for a model that cannot call tools.

Turn providers on and off

Credentials

Credentials live in auth.json, in the data directory. The file is written with mode 0600. Three shapes are stored: oauth, api and wellknown.

Use origami providers login to add a credential and origami providers list to see what is stored. ORIGAMI_AUTH_CONTENT supplies the whole store from the environment instead.

Flock: a model for subagents

A Flock profile sets the model that subagent sessions use, and an ordered list of fallbacks.

{
  "flock": {
    "profile": "home",
    "profiles": {
      "home": {
        "description": "local first, cloud second",
        "subagents": {
          "use": "lmstudio/qwen3-coder-30b",
          "fallback": ["anthropic/claude-sonnet-4"]
        }
      }
    }
  }
}

An absent or null profile turns routing off. An unknown key inside a profile stops the load. Fallback happens on an authentication error, on HTTP 401, 403, 404, 408 and 429, and on any 5xx. Status 400 and 422 do not trigger it, because a malformed request fails the same way everywhere.

Configure

Local models

Origami Coder expects an OpenAI-compatible server on your own machine. This is the product's central design choice.

Connect a server

In VS Code, set origami.engineUrl. The default is http://localhost:1234/v1, which is an LM Studio server on the same machine. The setting overrides the ORIGAMI_API_BASE environment variable.

The connect picker offers LM Studio as "Local — runs on your own GPU (recommended)". It fills in the base URL http://127.0.0.1:1234/v1 and writes a provider block with the package @ai-sdk/openai-compatible.

Ollama uses the fixed endpoint http://localhost:11434/v1. The extension recognises an Ollama block by the provider identifier ollama, or by a loopback address on port 11434.

Any other OpenAI-compatible server works. Write the provider block by hand, as in Models and providers.

What counts as self-hosted

The engine reads the host name of the base URL. These count as self-hosted:

• localhost, 0.0.0.0, ::1, and any name with no dot in it
• names that end in .local, .lan or .ts.net
• addresses in 127.*, 10.*, 192.168.*, 172.16.* to 172.31.*, and 100.64.* to 100.127.*

Longer timeouts for local hardware

A self-hosted endpoint gets a default chunk timeout and a default header timeout of 300000 milliseconds. A cloud endpoint gets neither. The reason is stated in the code: a large prefill on local hardware can run for minutes before the first token, and a stuck local stream has no server-side reaper.

Set options.chunkTimeout or options.headerTimeout in the provider block to change them.

The context window

A local server often does not report its window size. The extension probes for it in this order.

1. The LM Studio endpoint /api/v0/models. It uses loaded_context_length, and only when the model state is loaded.
2. The OpenAI-compatible endpoint /v1/models. It reads max_model_len, max_context_length or context_length.
3. For Ollama, the native endpoint /api/show. It reads the architecture context length, a bare context_length, or a num_ctx parameter.

The maximum context length of a model is deliberately not used, because that value can be far larger than the memory of the machine.

Connecting a server saves the window too

Connecting a self-hosted server (the LM Studio or vLLM preset) writes the probed window into the saved model entry, not only into the display. This never overrides a window you set by hand, and a failed probe never blocks the connection — it just leaves the entry bare.

Control LM Studio

When LM Studio runs on the same machine, the extension can drive the lms command directly. It looks for the binary in ~/.lmstudio/bin. It loads a model with a chosen context length and unloads models. A remote LM Studio cannot be driven this way.

Two known problems of local servers

Match the server capacity

Set options.max_concurrent to the number of requests your server handles at once. Parallel subagents then queue instead of starving the server.

Configure

Agents

An agent is a named set of a prompt, a model and a permission list. A primary agent drives the session. A subagent does work for the task tool.

Built-in agents

Three more agents are internal and hidden: compaction, title and summary. They have every tool denied.

The default agent is build. Set default_agent to change it. The value must name a primary agent that is not hidden.

Shipped archetypes

The VS Code extension installs six ready-made agents into the global agent directory the first time you open the Folds board or the Collab Agents pane. Each is an ordinary markdown agent definition, so it works exactly like one you write yourself.

Write your own

Put a markdown file at <config dir>/agent/<name>.md. The plural agents/ also works, and sub-folders become part of the name.

---
description: Reviews a diff and reports defects only.
mode: subagent
model: lmstudio/qwen3-coder-30b
temperature: 0.2
permission:
  edit: deny
  bash: ask
---

You review changes. Report defects. Do not fix them.

The body of the file is the prompt. Agents can also be written as JSON under the agent key of origami.json.

Frontmatter keys

The keys tools and maxSteps are deprecated. Use permission and steps. The key role is accepted and ignored.

Subagents

The task tool lists every agent whose mode is not primary and that the caller's task permission does not deny.

subagent_depth limits the nesting. The default is 1, so a subagent cannot start another subagent.

Create an agent file from the command line with origami agent create, and list agents with origami agent list.

Configure

Collab

A collab is a shared room. Several agents and one human read the same message log. Each agent keeps its own session, and the room keeps a task board and a cost ledger.

How it differs from a session and a subagent

An ordinary session is one agent and one human. A subagent is started by the task tool, it answers once, and it is then gone. A collab is durable: the message log, the roster, the board and the ledger are rows in the database, so the room survives a restart.

Each participant gets its own persistent child session. The session is created on the agent's first turn, not when it joins, so a roster entry that never speaks costs nothing.

By default, only one turn runs at a time in one collab, and turns are held in a queue. A room may opt into running several turns at once with concurrency: N (up to 4), but only when every member's own permissions deny every file-writing tool outright — a wide room may read and discuss, it may not build. A council-flavored room (see below) always dispatches wide, because its turns are sealed read-only regardless of the setting.

A collab is driven from the VS Code extension. There is no collab CLI command, no terminal UI screen and no HTTP route. The engine surface is a set of ACP methods, listed below.

Flavors: discuss and council

A collab has a flavor, set with collab_set_flavor: discuss, the default, or council. A room with no stored flavor is a discuss room.

In a council, one human question dispatches to every active member at once. Each member reads the room as it stood at the question, so no member sees a sibling's opinion before it answers. Once every member has settled, the lead — or the first member in roster order if there is no lead — reads every opinion and writes one synthesis for the room. Council turns are sealed read-only, so a council may run wide with nothing to configure.

A hop, in a council, is the whole round: the opinions and the synthesis together cost one hop, not one each.

Make an agent collab-capable

An agent can join a room only if its definition file sets collab: true. The key is not a known agent key, so it is moved into options, and the roster check reads it from there.

---
description: Reads code and reports what it found.
mode: subagent
model: lmstudio/qwen3-coder-30b
collab: true
vision: true
---

You are the scout. You read the repository and report facts.

The check fails closed. An agent without the key, or with frontmatter that does not parse, is refused with a message that names the file.

vision: true is a second, separate opt-in. It controls images only. See Images below.

The base prompt

Every collab agent gets a built-in base prompt above its own persona. The prompt states what the room is, what the tools do, and who routes work next. Live room state is added below the persona.

To replace the built-in text, write collab-agent-base.md in the global config folder. A missing, unreadable or empty file is not an override, and the built-in text is used.

The state block below the persona is rebuilt for every turn. It names the roster, the lead, the objective, the hops left and the first open tasks.

Run a collab

The composer in the VS Code chat view has nine slash commands for a room.

A line that is not one of these nine is posted to the room as a message.

The lead and addressing

One agent is the lead. An unaddressed human message goes to the lead alone. With no lead set, nobody is woken, and the post is answered with the notice no-lead.

The lead is kept on an active agent. An empty seat is filled by the first agent in join order. If the lead is removed, the next agent takes the seat. Roster order is join order, not alphabetical order.

To address named agents, write @slug in the composer. The composer parses the line and sends a structured list of slugs. Unknown slugs are dropped, and the engine checks the list against the active roster before it writes anything.

Routing reads the kind of a message and its structured list of slugs. It never reads the prose. An @name written inside a sentence is a reference, and it wakes nobody. An ordinary message from an agent also wakes nobody: agents route work with the tools below, not with text.

The rules are an ordered list, and the first rule that has an opinion decides. In order: never the author, a human message to the named agents, an unaddressed human message to the lead, answers and directed messages to nobody, finished and reopened board work back to the agent that owns it, and silence for everything else. A rule that throws an error ends the decision at "skip".

Tools inside a turn

Eight tools exist only inside a collab turn. They are added to the request when a collab turn is present, and never at any other time, so an ordinary chat sees none of them. They are part of the protocol, so a permission list that denies by default does not remove them.

A target is resolved against the active roster by slug first, then by display name. A leading @ is removed, and the match ignores letter case.

ask is refused, in this order, when the target is not on the roster, when the target is already waiting further up the same chain, when the chain is three deep, when the room has no hops left, and when the target session is busy. A refusal is returned to the one model that called the tool. The room does not see it.

The hop budget

A hop is one agent turn. One human message buys a fixed number of hops. When they are spent, the agents stop, and the room waits for a human.

The cap is stored for each collab as loop_breaker_cap. It must be null or an integer that is not negative. A new human post refills the budget. A stop spends all of it.

The budget is shared by reference along a chain of asks, so a deeper call cannot buy more hops. The agents are told how many wakes are left on each turn.

The task board

A task is the unit of accountability between agents. A task has one of four states: open, claimed, done and accepted. An ask opens a task by itself, and a human can add one by hand.

The board records the title, the owner, the agent that created it, the result, the note that reopened it, and the message that created it. A board move is a record. By itself it wakes nobody, except that finished work wakes the agent that asked for it, and reopened work wakes its owner.

A task title is cut to 80 characters, because the title is a label and the full brief is in the message.

Cost and tokens

One row is written for each completed turn, including a silent turn. A silent turn still spends tokens.

Each row holds the agent slug, the model as provider/model, the input tokens, the output tokens, the cost, and the agent that asked for the turn on a nested turn. Spend is summed from the step records of the turn.

The ledger returns a page of rows and a set of totals for each agent. The totals are summed in the database, so they cover the whole ledger and not only the page. The page holds 100 rows by default.

Images

Only a human can post an image. No agent tool accepts one. Images are stored in the message row as data: URLs, because the log is the record.

An image is refused if the message carries more than four images, if it is not a data: URL, or if it is larger than 2 MB. The check runs before anything is written.

An agent with vision: true receives the image. An agent without it receives a note that says how many images it cannot see, and the base prompt tells it to say so and to ask a participant that can see them. If the definition cannot be read, the agent is treated as unable to see.

What is stored

The sequence number is unique for each collab, so the same number cannot be used twice in one room. Every table refers to collab and is deleted with it. Removing an agent is a soft delete, and adding it again keeps its session and its position in the log.

The tables are created by three migrations: the first adds the collab, the roster and the log; the second adds the board, the ledger and six columns; the third adds the images column.

Which agent is mid-turn, and whether the loop breaker has tripped, are computed from the log. They are not stored, so a restart cannot leave a stale state behind.

Engine methods

The engine exposes collab over ACP as twenty-three extension methods. Each method that acts on one room needs a collabId.

There is no method that creates or edits an agent definition. A definition is a file, and the extension edits it directly.

A collab publishes no event. A client reads the room by calling collab_state again.

Limits

The roster size and the length of the log are not limited. There is no timeout and no rate limit. The hop budget is the only control on how long a room runs.

The number of steps in one turn comes from the steps key of the agent definition. See Agents. A turn that hits that cap is not posted to the room.

Configure

Folds board

The Folds board is a ticket kanban over git worktrees, in the VS Code extension. A ticket is a markdown file. Starting work on it provisions a worktree and a session.

Tickets

A ticket lives at <repo>\.origami\tickets\<id>.md, with an id of t- plus six base36 characters. The frontmatter holds scalars only. Acceptance criteria are - [ ] lines under an ## Acceptance heading, and an append-only ## Log records history. A status is one of triage, todo, pending, in_progress, done, merged or closed.

Engine tools

Reading never asks. Every mutation goes through the board permission key. A bare repo of . is refused outside a git repository, so a ticket cannot land at the drive root.

The repo registry

The extension writes a cross-repo registry at ~\.origami\repos.json, with an atomic write. The board tools, and the standalone board MCP bridge, resolve a repo name against this file.

Configure

Commands

A slash command is a prompt template with a name. Four come with the engine. You can add your own.

Built-in commands

The registry also holds one command per MCP prompt, and one command per skill.

Write your own

Put a markdown file at <config dir>/command/<name>.md. The plural commands/ also works. A sub-folder becomes part of the name, so command/git/sync.md is /git/sync.

---
description: Summarise recent git changes
agent: build
---

Summarise what changed in the last $ARGUMENTS commits.
Group the changes by area and name anything risky.

Frontmatter keys

The markdown body is the template. Commands can also be written as JSON under the command key of origami.json.

Arguments

1. The argument text is split into words. Quoted groups stay together, and the quotes are removed.
2. $1, $2 and so on take the words in order. The highest number in the template takes every remaining word. A missing position becomes an empty string.
3. $ARGUMENTS takes the whole argument text, unsplit.
4. A template with no $N and no $ARGUMENTS gets the argument text added at the end.
5. Text inside !`...` is run as a shell command, and the output replaces it.

The model of a command is its own model, then the model of its agent, then the model of the session.

Commands that belong to one surface

Some commands are not engine commands. They work only in the client that owns them.

• VS Code: /firstfold, /spend, /loop, /compose. See VS Code.
• Terminal: /sessions, /models, /themes and the rest of the list in Terminal UI.

Configure

Skills

A skill is a markdown file of reusable knowledge. The model loads it when the task matches.

Where skills are found

1. Every configuration directory: skill/**/SKILL.md and skills/**/SKILL.md. This covers .origami/skills/ in the project, ~/.origami/skills/, and the global configuration directory.
2. External directories: .claude/skills/**/SKILL.md and .agents/skills/**/SKILL.md, both in your home directory and in the project.
3. Paths listed in skills.paths. ~/ is expanded.
4. Indexes listed in skills.urls. The files are downloaded into the cache directory.
5. Skills supplied by an agent plugin.

Claude Code skills in ~/.claude/skills are not read by default. Set ORIGAMI_DISABLE_CLAUDE_CODE_SKILLS=false to read them. ORIGAMI_DISABLE_EXTERNAL_SKILLS turns off every external directory.

The file

---
name: tdd
category: workflow
description: Write the failing test first, then make it pass.
---

# Test first

Reproduce the defect in a test before you change the code...

Everything after the frontmatter is the body. Two files with the same name produce a warning, and the last one wins.

How a skill runs

• The model calls the skill tool with the skill name. The body then enters the conversation.
• You type /<name>. Every skill is registered as a slash command, unless a command or an MCP prompt already owns that name.

The system prompt lists only the name and the description of each permitted skill. The body is read only through the skill tool.

Limit which skills an agent may use

Skills are filtered per agent by the skill permission key. There is no permission field inside the skill file.

{
  "agent": {
    "reviewer": {
      "permission": { "skill": { "*": "deny", "code-review": "allow" } }
    }
  }
}

The folder of a skill is added to the allowed external directories, so the agent can read the scripts/ and references/ beside it without a prompt.

origami debug skill lists every skill that the engine found.

Configure

Tools

A tool is a function that the model can call. Each one is subject to the permission rules.

Files and shell

For a GPT model, apply_patch replaces edit and write.

Work and delegation

Web, charts and the browser

Board and messages

Tools behind a flag

Your own tools

Put a JavaScript or TypeScript file at <config dir>/tool/<name>.ts. The plural tools/ also works. Each exported object with args, description and execute becomes a tool. The default export takes the file name; another export takes <file>_<export>.

A plugin can add tools too, and can rewrite the description and the parameters of any tool. See Plugins.

Size of tool output

Output above tool_output.max_lines (2000) or tool_output.max_bytes (51200) is written to a file, and the model receives a shorter preview with the path.

Configure

Memory

Memory is a folder of markdown files the model reads with the read tool. One index file loads every turn; every other file loads only when the model asks for it.

The layout

~/.origami/memory/              global
<worktree>/.origami/memory/    project

MEMORY.md                       the index, loaded every turn
<topic>.md                     one topic, read on demand
inbox.md                        facts waiting for a home

MEMORY.md holds one line for each topic: a name and a short hook. The engine appends a footer telling the model to read a topic file with the read tool before it acts on a hook. A machine with only the older flat memory.md still loads that file; the two forms are never both active.

Write to memory

The remember tool appends a dated fact to a topic file, then updates that topic's line in the index. An existing hook line is never overwritten by a new fact. Topic files grow without a size limit; length only costs tokens once the model reads that file.

/dream

The /dream command curates the store. It reads recent sessions plus the current index and topics, then stages a full proposed replacement folder for you to approve, revise or disapprove. Approving backs up the live folder first, then writes the staged files one by one.

Memory graph

The VS Code sidebar and the Full editor tab both show memory as a force-directed graph of the topic files and their wikilinks, with a live filter on title, tags and path.

Configure

Permissions

Every tool call is checked against a rule list. A rule gives one of three answers.

The three answers

When the user is asked, the possible replies are once, always and reject.

Write the rules

{
  "permission": {
    "bash": { "git status*": "allow", "*": "ask" },
    "edit": "allow",
    "webfetch": "ask",
    "external_directory": { "*": "ask" }
  }
}

A bare string is shorthand. "permission": "ask" means {"*": "ask"}.

The keys

These keys accept either an answer or a map of pattern to answer: read, edit, glob, grep, list, bash, task, external_directory, lsp, skill, plugin.

These keys accept an answer only: todowrite, question, webfetch, websearch, doom_loop.

Other keys are allowed. A plugin tool is addressed as plugin:<name>:<tool>.

Patterns

• * matches any text. ? matches one character.
• Backslashes become forward slashes before the match, in both the pattern and the value.
• A pattern that ends with a space and a star also matches the bare command, so git status * matches git status.
• The match ignores letter case on Windows only.
• The last rule that matches wins. Key order in the file is preserved and is therefore meaningful.

The defaults

Before your rules are applied, the engine starts from this set.

An agent adds its own rules on top. The plan agent denies every edit outside .origami/plans/, and allows delegation only to explore.

Approve everything

--auto approves every permission that is not explicitly denied. The command line describes it as dangerous. It works on the terminal command and on run. The setting is read live, so a change during a turn takes effect at once.

Saved answers

An answer of always is stored. In VS Code, run Origami: Reset saved permissions to clear the stored answers of the workspace.

From the environment

ORIGAMI_PERMISSION holds JSON that is merged over the permission block. Invalid JSON is skipped, with a warning.

Configure

MCP servers

A Model Context Protocol server adds tools and prompts. Origami Coder connects to local processes and to remote servers.

A local server

{
  "mcp": {
    "my-server": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-server"],
      "cwd": "./tools",
      "environment": { "TOKEN": "{env:MY_TOKEN}" },
      "enabled": true,
      "timeout": 5000
    }
  }
}

A remote server

{
  "mcp": {
    "docs": {
      "type": "remote",
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer {env:DOCS_TOKEN}" },
      "enabled": true
    }
  }
}

Manage servers

Use origami mcp add, origami mcp list, origami mcp auth, origami mcp logout and origami mcp debug <name>. In the terminal interface, /mcps turns servers on and off.

A plugin may also supply servers. Plugin servers are merged before the servers of the configuration file.

Protocol

The client targets the 2026-07-28 revision and negotiates with server/discover. A server that answers only the older initialize handshake is treated as legacy. The client identifies itself as origami.

Keep the tool list small

MCP tools are deferred by default. Each server then costs one catalog line until the model searches for it with tool_search. Change this with experimental.tool_search.

Code mode is the other option. One execute tool replaces the individual MCP tools, and the model writes a short program that calls several of them.

Configure

Themes

The terminal interface and the VS Code extension have separate theme systems.

Terminal themes

Set the theme key in tui.json, or press the theme key (<leader>t by default) to open the picker.

The built-in names are:

aura, ayu, carbonfox, catppuccin, catppuccin-frappe, catppuccin-macchiato, cobalt2, cursor, dracula, everforest, flexoki, github, gruvbox, kanagawa, lucent-orng, material, matrix, mercury, monokai, nightowl, nord, one-dark, origami, orng, osaka-jade, palenight, rosepine, solarized, synthwave84, tokyonight, vercel, vesper, zenburn.

The fallback theme is origami.

Your own theme

Put a JSON file at <config dir>/themes/<name>.json. This works in the global configuration directory and in each .origami directory.

Priority runs from low to high: built-in themes, plugin themes, your own files, then a theme generated from the terminal colours.

VS Code themes

The extension contributes five colour themes: Origami Meadow, Origami Harbour, Origami Ember, Origami Midnight and Origami Custom.

The command Origami: Toggle Theme steps through meadow, harbour, ember, midnight and custom. The setting origami.syncVsCodeTheme decides whether the editor theme follows the dashboard theme: ask, always or never.

Configure

Keybinds

The terminal interface uses a leader key. Overrides go in tui.json.

Change a binding

{
  "keybinds": {
    "session_new": "ctrl+t",
    "app_debug": "<leader>d",
    "messages_copy": "none"
  }
}

The value none or false removes a binding. A comma separates alternatives. <leader> stands for the leader key. An unknown binding name is dropped, and does not stop the load.

The leader key is ctrl+x. leader_timeout sets how long the leader waits, in milliseconds. The default is 2000.

Session and application

Model and agent

Messages and the prompt

Diff viewer

VS Code has its own bindings. See VS Code.

Develop

Plugins

A plugin adds tools, providers, authentication methods, and hooks around the turn.

Load a plugin

Two ways work.

• Put a .ts or .js file in <config dir>/plugin/ or <config dir>/plugins/. It loads with no configuration entry.
• Name it in the plugin array of the configuration. A relative path is read from the directory of the configuration file. Any other value is treated as an npm package name and installed.

{
  "plugin": [
    "./plugins/my-plugin.ts",
    ["some-npm-plugin", { "option": true }]
  ]
}

origami plugin <module> installs a plugin and writes the entry. It accepts --global and --force.

--pure or ORIGAMI_PURE starts the engine with no external plugins.

Plugins from agent-plugins.org are listed separately in agentPlugins, and managed with origami agent-plugin add and origami agent-plugin list.

Hooks

The package is @origami/plugin.

Experimental hooks

The package also exports @origami/plugin/tool and @origami/plugin/tui. Terminal plugins are declared in tui.json, under plugin and plugin_enabled.

Develop

SDK and HTTP API

The SDK package starts a server and talks to it from JavaScript.

The package

The package is @origami/sdk. Its entry points are ., ./client, ./server, ./v2, ./v2/client, ./v2/server and ./v2/types.

The main entry exports createOrigamiClient, createOrigamiServer, and createOrigami, which starts a server and returns both.

import { createOrigami } from "@origami/sdk"

const { client, server } = await createOrigami()

Types from the API document

The client types are generated from the OpenAPI document. The generated document is kept in the repository, and origami generate writes it.

Handlers

The @origami/server package holds the handler groups: agent, command, credential, event, fs, health, integration, location, message, model, permission, project-copy, provider, pty, question, reference, session and skill.

The editor protocol

origami acp starts an Agent Client Protocol server. The VS Code extension uses it. Use --cwd to set the working directory.

Help

Troubleshooting

Most reports come from one of these causes.

A change does not appear

Find out which artifact holds the change. A change under packages/vscode/ needs a new extension. A change under packages/engine/ needs a new engine binary. Rebuilding one does nothing for the other.

Check what went into the engine binary:

grep -a "someSymbolYouAdded" ~/.origami/bin/origami.exe

An old engine still serves the session

A deploy replaces the binary, but a window that is already open keeps the process that it started. The extension compares the modification time of the binary at start with the time on disk now, and reports a stale engine.

Start a new session, or reload the window.

Engine edits do not take effect

Set origami.devEngineSource to the path of a packages/engine source tree. The extension then runs the engine from source with Bun, and a window reload picks up the edits. With an empty or invalid value, the compiled binary is used and a reload changes nothing. The output channel of the extension logs which one started.

The model is unreachable

The banner has four states: ok, probing, offline-local and offline-remote. The local state means that the loopback LM Studio has no model loaded. Check that the server runs, that a model is loaded, and that origami.engineUrl ends in /v1.

The context meter shows nothing

A local server often reports zero for the window size. The meter treats zero as "not known" and keeps the last real value. The extension probes the server for the true window size.

A long local request stops

A self-hosted endpoint has a default chunk timeout and header timeout of 300000 milliseconds. Raise options.chunkTimeout and options.headerTimeout in the provider block, or set them to false to remove the limit on the whole request.

The configuration file is refused

An unknown key at the top level stops the load. The message names the key. Note that theme, keybinds and tui belong in tui.json.

Print what the engine really read:

origami debug config
origami debug paths

See the logs

origami --print-logs --log-level DEBUG

Turn behaviour off

Legal

Attribution

Origami Coder began as a fork of OpenCode.

Upstream project

OpenCode is the upstream project. Origami Coder started as a fork of the OpenCode repository on GitHub.

License

OpenCode is licensed under the MIT License. Its copyright notice reads:

Copyright (c) 2025 opencode