woodls code

Install

curl -fsSL https://woodls.com/install.sh | sh

On Windows, in PowerShell:

irm https://woodls.com/install.ps1 | iex

The install page says more about both. woodls code runs on a Mac with Apple silicon, on Linux (x86-64 or ARM64, glibc 2.28 or later), and on Windows 10 or 11 inside WSL2.

woodls’ own engine, for running a model file on this computer (--this-computer):

• Mac: it comes with woodls and runs on the graphics chip.
• Linux on x86-64, and Windows through WSL2: woodls code asks to fetch it the first time, saying its size: 59 MB for the processor’s engine, or 0.34 to 1.6 GB for an AMD or NVIDIA card’s, each checked against woodls’ signed list. For a card’s engine, c fetches the processor’s smaller one instead. It needs a Linux with glibc 2.39 or later (Ubuntu 24.04, Debian 13, Fedora 40) and a working sandbox.
• Linux on ARM64: no engine yet. Run the model in Ollama or LM Studio, and woodls code finds it there as your server.

On Windows, woodls code runs your project’s commands in Ubuntu: install the tools it builds and tests with there (build-essential, Node or Rust, say). Windows’ own .exe programs aren’t reached from inside its sandbox, and projects that need Windows itself, such as .NET Framework, need Windows. Projects kept in Ubuntu’s own folders are much faster: open Ubuntu’s window, go to the project and run woodls code there. /copy puts text on Windows’ clipboard.

On Ubuntu 24.04, AppArmor stops bubblewrap’s sandbox as installed, so every command asks first and go ahead is off. Troubleshooting shows the narrow change you can choose to make.

Your first ten minutes

1. Give it a model. Any one of these will do:

export ANTHROPIC_API_KEY=…
woodls code connect anthropic
woodls code \
  --server http://192.168.1.20:8000/v1
woodls init --invite CODE

A provider’s key in its usual variable; or kept by woodls, typed where it isn’t shown; or your own OpenAI-compatible server; or, with an invite, your account on the woodls network, paid in credits. Ollama or LM Studio running with a model are found by themselves. woodls code models lists the eight providers and where each key comes from, never the key.

2. Start in your project.

cd your-project
woodls code

• With a woodls account, woodls code uses the public network, paid in credits, unless you name another place: --model PROVIDER/MODEL, --this-computer, --server or --group. When no computer on the public network serves a model, woodls code offers what it finds here for that task only, a provider’s key, Ollama or LM Studio, or a model file, and asks first.
• The model. It says which it uses and where: “woodls code uses Anthropic · claude-sonnet-5-5 · key from ANTHROPIC_API_KEY · billed to your key; /model changes it”. With several, you choose once by number and it’s kept.
• The trust screen. If the project has its own rules files, skills, hooks, MCP servers or plugins, woodls code lists them first. y uses them; n runs without them. A project can never grant itself a permission.
• The tour, five short pages the first time: the modes, where it runs, the / commands, ! and @, and undo. Enter goes on, Esc skips it.

3. Ask for something small. Type it and press Enter: “add a test for parse_date that covers a leap day”. The live line says what it’s doing this second. Esc stops the step under way. You can also start with the task: woodls code "add a test for parse_date".

4. Answer a card. In ask first, the default mode, every change and every command that isn’t read-only shows a card first: the diff, or the command and why.

• An edit: y yes, e every edit in this task, n no (and say why), s stop, d the whole change.
• A command: y yes, a always here (kept as a permission for this project), n no, s stop.
• Tab on a card adds a comment. A card’s keys wake 400 ms after it shows, so fast typing never answers one.

5. See what changed. /diff shows every change of the task, file by file. Ctrl+T shows the task’s tree. /watch opens the task live in your browser.

6. Undo it. /undo puts back what your last message changed; /redo brings it back. Esc Esc goes back to any earlier message, files and all.

7. Commit. /commit shows the message and the files first; /commit yes makes it.

8. Leave, and come back. Ctrl+D or /quit leaves; the task stays on this computer. woodls code --resume in the same folder picks up the latest task, and --resume parse_date one by a part of its name.

Choose a model

woodls code --model anthropic/claude-sonnet-5-5
woodls code models
woodls code models openai
woodls code models --refresh

Inside woodls code, /model (or Alt+P) lists the models you can reach and moves the task to another from the next step.

• Keeping a key: woodls code connect anthropic (or /connect anthropic inside) takes it unseen, or piped in, and checks it with a request that costs nothing. It goes to the macOS Keychain, or on Linux to a file only you can read. woodls code disconnect anthropic takes it away. A key never goes in a setting, a session, a log, your history, or anything sent to woodls.
• Cost: a provider’s steps show an estimate on each step and in the window. Your provider’s bill is the real figure.
• Free tiers: a provider’s rate limit is waited out. Only an empty account’s own words are read as no credit left there.

Your own server, and this computer:

woodls code \
  --server http://192.168.1.20:8000/v1 \
  --key-env MY_KEY_VAR
woodls code \
  --server http://127.0.0.1:8080/v1 \
  --window 32768
woodls code --this-computer --model gpt-oss:20b

• Your server is any OpenAI-compatible address: vLLM, llama.cpp’s server, LiteLLM, LM Studio. Only the variable’s name is kept, never the key. woodls can’t see where it runs or who reads it, and charges nothing.
• This computer runs a model file you already have in woodls’ own engine, sandboxed to that one file: Ollama’s downloads, LM Studio’s files, the Hugging Face cache, and the file your woodls host serves. No model yet? woodls models get qwen3-8b downloads one, 5.0 GB, checked.
• Ollama and LM Studio themselves, when they’re running, are found as your server.

The woodls network needs an account (woodls init --invite CODE):

• A private group (--group home) is your computers and your friends’, free, and encrypted between you and the computer answering.
• The public network (--public) is other people’s computers, paid in credits; --budget (5 a task) and --daily-limit (50 a day) cap it. The computer answering can read each step, so secrets are taken out first.

What each place gets (/privacy says it for the task you’re in):

How it works with you

/plan, /ask, /go and --mode plan|ask|go choose one.

More cards. o runs a command once outside the sandbox, for one that needs the internet (an install, say); it’s never kept, and asks every time. A web page, an MCP tool, or what /undo can’t bring back has its own card.

Permissions live outside your project, in ~/.woodls/code/permissions/, so a project can’t grant itself anything. /permissions lists them; /permissions allow|ask|deny WHAT adds one, and /permissions forget N drops one. Deny comes first, then ask, then allow.

Claude Code’s shapes are read too, such as Bash(npm test:*). --allow RULE allows one for this task only.

Always asked, in every mode: protected files (.git/ is never changed; .woodls/, .agents/, .claude/, .github/workflows/, .mcp.json, AGENTS.md, CLAUDE.md, .envrc, .npmrc and the like ask), .env and key files, paths outside the project, and files /undo can’t bring back. Never: sudo, git push and the other commands that reach a remote (/pr pushes, as you, after your yes), rm aimed at / or your home folder, and curl … | sh.

The sandbox. Commands run in the operating system’s sandbox: Seatbelt on macOS; bubblewrap, Landlock and seccomp on Linux.

• They can write only in the project, a private temporary folder and folders you add with --add-dir; never in .git.
• They can’t read ~/.ssh, ~/.aws, ~/.woodls, cloud credentials, your keychains or your browsers’ data, and variables named like keys and secrets are left out of their environment.
• They reach no network until you allow sites: reach packages or reach example.com.
• /sandbox says what this task’s commands may write, read and reach.

What it can do

The model can read files and pictures, search the project, edit, write (a long file in parts) or apply_patch, run a command in the sandbox, keep a short plan, ask you a question in plan mode, fetch a web page’s text on this computer or a private group, after a card, and use your MCP servers’ tools, helpers and agents.

• @file attaches a file, @app.py#10-40 its lines, @shot.png a picture, @server:uri an MCP resource; Tab fills in a name.
• !command runs a command of your own, as you, outside the sandbox.
• Ctrl+V pastes a picture on a Mac, for a model that sees them. Pictures aren’t scrubbed, so the first one to another computer asks first (--send-pictures skips that card).
• After an edit, the errors it brought in come back, where a language server such as rust-analyzer, pyright, typescript-language-server, gopls or clangd is installed.
• Ctrl+G writes your message in your editor.

Seeing what it does

• The live line says what it’s doing this second: a file and its lines so far, the latest line of its thinking, or what it waits for. A model that says nothing for 20 seconds is said.
• Ctrl+O shows a command’s whole output; Ctrl+T (or woodls tree) the task’s tree; Ctrl+P (or /prompt) exactly what the next step will send, with its size and cost.
• /diff reviews every change: m marks a file reviewed, c turns a comment into your next message, u puts one file back.
• /status, /context (how full the model’s window is), /credits (what the task spent) and /report (the task step by step).
• /export writes the task as Markdown; /export html as one file to share. /copy puts the last answer on the clipboard.

In your browser

/watch (or woodls code --watch) opens the task live in your browser: its steps as they happen, what it’s doing this second, a preview of the web pages it writes, and buttons to answer its questions, stop it or undo. woodls Studio has the rest.

Context and memory

Rules files. woodls code reads yours in ~/.woodls/ (AGENTS.md, WOODLS.md and rules/), then the project’s from its top down (AGENTS.md, or CLAUDE.md where there’s none, WOODLS.md, .woodls/rules/ and .claude/rules/), then WOODLS.local.md. The nearest win. All of them share 2,000 tokens a step, so keep rules short. /rules lists what’s read; /init drafts an AGENTS.md for your yes.

The context. /context shows how full the window is. /compact keep the API design summarises older steps now. /add-dir DIR lets it read and change another folder for this task.

Memories are off until you turn them on with --memory. /remember WORDS keeps one, /memory lists them, /learn proposes some, and /promote N moves one into WOODLS.md.

Tasks and undo

• Each task is named from your first words. /name renames it and /new starts another.
• Picking one up: woodls code --resume, --resume NAME, or /resume inside.
• Going back: /rewind or Esc Esc goes back to an earlier message, asking whether to put the files back too; /fork copies the task into a new one.
• Undo: a checkpoint is taken before a turn’s first change, in ~/.woodls/code/snapshots/, never in your git. /undo puts back the last turn (/undo anyway if you changed those files since); /redo until your next message. /try tries your last message again; /try 2 makes two attempts and you keep one; /attempts N goes back to any of them.
• Your history is sealed with a key on this computer. woodls history lists it; woodls forget deletes it all.

Agents and helpers

A helper does one job with a context of its own and reports back. Agents are helpers you define.

• /agents lists them and makes a new one (n). Files are Claude Code’s subagent format, in .claude/agents/ or .agents/agents/ in a project, or ~/.woodls/agents/ for you.
• From the shell: woodls code agents list, show NAME, remove NAME, and new, as below.
• @agent-name in a message hands the job to that agent first.
• Helpers are on for Anthropic, OpenAI and Google models, and off for open models until measuring shows they help: --helpers on|off, /helpers on|off, /helper JOB.

woodls code agents new --name test-writer \
  --description "Writes pytest tests" \
  --may edit --instructions "…"

Background tasks, worktrees and goals

woodls code --bg "add a retry to the uploader"
woodls code tasks
woodls code --resume "add a retry"
woodls code tasks keep "add a retry"
woodls code --worktree fix-auth

• A background task runs in a git worktree of its own and returns at once. A question waits for you. woodls code tasks lists them; stop, keep and drop act on one. At most two run at once.
• Worktrees are made from HEAD, outside the project; one you didn’t change is removed when you leave.
• /goal COMMAND keeps working until your command passes; the same failure three times in a row stops it.
• /review runs a look-only check of the changes; /second-look re-reads each turn for what it might have missed; /aside QUESTION asks a side question.
• Ctrl+B moves a running command to the background; /jobs lists them.

Git

/commit commits this task’s files, showing the message, the files and the hooks git will run first; /commit yes makes it. /pr [TITLE] drafts a pull request and, after your y, pushes and opens it with gh. The model never pushes.

Extending it

woodls mcp add github -- \
  npx -y @modelcontextprotocol/server-github
woodls mcp add --transport http docs \
  https://example.com/mcp
woodls mcp list
woodls mcp remove github

• MCP servers go in ~/.woodls/mcp.json, or with --scope project in the project’s .mcp.json, which the trust screen asks about. /mcp lists them and /mcp signin NAME signs in through your browser.
• Skills: a folder with a SKILL.md, in ~/.woodls/skills/ or the project’s .agents/skills/; each runs as /NAME. /skills lists them.
• Hooks: Claude Code’s shape, in ~/.woodls/hooks.json or the project’s .woodls/hooks.json. /hooks lists them.
• Plugins: ~/.woodls/plugins/ or the project’s .woodls/plugins/. /plugins lists them.
• Moving in: woodls code import claude (or codex, opencode) brings another tool’s MCP servers, hooks, skills, rules files and permissions, after showing what it would write.
• Your keys: ~/.woodls/keys.json. Your status line: a command of yours, set with woodls config set statusline, whose first line shows under the footer.

Scripts and editors

woodls code --run "fix the failing test" \
  --mode go --json
woodls code --run - < task.txt
woodls code --run "count the TODOs" \
  --output-schema out.json
woodls code --run "make the tests pass" \
  --goal "cargo test"
woodls code --acp
woodls mcp serve
woodls code opencode

• Exit codes: 0 done, 1 error, 2 the budget ran out, 3 it needed a yes nobody could give, 4 a limit, 5 refused, 6 blocked with --goal, 130 stopped.
• --json gives one event a line; fields are only ever added.
• --bare reads no rules files, hooks, MCP servers, skills or plugins; your permissions and the sandbox still hold.
• --acp is for editors that speak the Agent Client Protocol, such as Zed and JetBrains: add woodls code as a custom agent, the command woodls with the arguments code and --acp. Cards become the editor’s permission requests. It’s tested as an editor drives it, and hasn’t been tried in those editors themselves yet.
• woodls mcp serve gives another agent woodls code’s memories, your background tasks and your credits, to read. It never runs commands, edits files or spends.
• woodls code opencode (or goose, codex, or claude --experimental) starts that agent on the woodls network’s models, through a private proxy on this computer.

Settings

woodls config lists every setting with what each is now; woodls config set KEY VALUE changes one and woodls config unset KEY clears it. woodls code’s own need no account: colours, summary.point, summary.reread, statusline, language-servers and thinking-line. Inside, /config shows the settings that apply and /colours NAME changes the colours for the session.

Where things are kept, and privacy

Everything is in ~/.woodls: your tasks (sealed), checkpoints, permissions, trust answers, settings and, where there’s no keychain, provider keys. The project gets nothing but what you ask for.

What leaves this computer is each step, to the place the model runs: your messages, the rules files, what woodls code read, commands’ output and the project’s outline. Before every step, a scrubber takes out secrets, keys, emails, phone numbers, your home folder’s path and your git name, and puts them back in answers. Nothing catches everything, and pictures aren’t scrubbed. --no-scrub turns it off. woodls’ own server sees a step only on the public network, and keeps no prompt or answer.

Every command

The keys (? on an empty line lists them all): Enter sends; Esc stops the step; Esc Esc goes back to a message; Shift+Tab changes the mode; Alt+P the model; Ctrl+T the tree; Ctrl+P what the next step sends; Ctrl+O a command’s whole output; Ctrl+B a command to the background; Ctrl+G your editor; Ctrl+C clears, stops, then quits; Ctrl+D quits when the line is empty.

What’s measured

How woodls code did on our own 40-task yardstick, and where and when it was run, is on Use AI. Not measured yet: woodls code on paid providers’ models, helpers on open models, and the editor protocol in Zed or JetBrains themselves.

When something goes wrong, troubleshooting has what woodls code says and what to do.