Open Walnut

Watch the demo (6 min)

Open Walnut runs Claude Code on your laptop and on your remote dev boxes, and shows every session in one web page. A small daemon on each host owns the claude processes, so a session on a dev box keeps working when your SSH connection drops or your laptop sleeps. No tmux. Walnut installs that daemon over SSH for you, and each session gets its own diff of every file it changed.

Next to the sessions sit your tasks, notes, and long-term memory, and a personal AI that can plan work, find context, and start sessions for you. Open Walnut is self-hosted, local-first, and has no telemetry.

• Personal AI: Ask Walnut to manage tasks, find information, write and search notes, start coding sessions, and run scheduled routines.
• Claude Code workspace: Run and monitor multiple Claude Code sessions side by side with live output, permission controls, terminals, files, and session history.
• Local and remote sessions: Use the same web app for sessions on your laptop and any configured SSH host.
• Durable sessions: Sessions keep running across browser disconnects, dropped SSH connections, and Walnut server restarts.
• Change review: Inspect a per-session diff, comment on individual lines, and send the review back to the same session.
• Tasks and projects: Organize work as Project -> Task -> Subtask, with an Inbox for tasks that do not belong to a project.
• Notes and memory: Keep Markdown notes with wiki links and search them together with task, session, and memory data.
• Local-first storage: Core data is stored under ~/.open-walnut/ in JSON, YAML, Markdown, and SQLite files.

• macOS or Linux. The one-line installer and Homebrew bring their own Node; the npm and checkout routes need Node.js 22 or newer (curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash then nvm install 22).
• git, only for the checkout route below (macOS: xcode-select --install, Ubuntu: sudo apt install git)
• Linux: a C library from 2019 or later (glibc 2.29+: Ubuntu 20.04+, Debian 11+, AL2023, Fedora). Older distros compile one native module and need a newer Python and GCC first; npm start prints the exact commands, and Getting Started has them too.
• Claude Code, signed in once (npm install -g @anthropic-ai/claude-code, then run claude)

That is the whole AI setup. Every AI turn Walnut runs is a Claude Code session: Ask Walnut (the Walnut agent), your coding sessions, scheduled routines, and the agents a session hook dispatches all use the claude you already have, however it signs in (Anthropic account, Bedrock, or Vertex). An Anthropic API key or AWS Bedrock credentials are optional, and they change only where the small single calls go (session titles, summaries, voice cleanup, quick parses): by default those also go through your Claude Code login, and Settings → Ask Walnut Provider points them at a provider instead.

One command on macOS or Linux. It needs nothing installed first, not even Node:

curl -fsSL https://github.com/EvanZhang008/open-walnut/releases/latest/download/install.sh | sh
walnut web

It downloads the newest release for your machine, with its own Node inside, checks it against the release's checksums, puts it in ~/.local/share/open-walnut and links walnut into ~/.local/bin. Running it again installs the newest release over the old one.

With Homebrew:

brew install evanzhang008/tap/open-walnut
walnut web

With Node 22 or newer, the npm package (nothing to build either):

npm install -g open-walnut
open-walnut web

To work on Walnut itself, run it from a checkout instead:

git clone https://github.com/EvanZhang008/open-walnut.git
cd open-walnut
npm install
npm start

Open http://localhost:3456 and follow the setup screen. The first start downloads the default local embedding model, Qwen3-Embedding-0.6B (approximately 640 MB), in the background.

For provider options, remote hosts, and troubleshooting, see Getting Started.

Walnut checks npm once a day for a newer release and shows it in the notification panel (System) and at the bottom of Settings, with the one command that updates your install. Restarting applies it, however you installed it (the one-line installer and Homebrew update with their own Node): open-walnut web installs a newer published version before it starts (Settings > General > Install updates on start, or updates.auto: false in config.yaml, or WALNUT_NO_AUTO_UPDATE=1, to turn that off). open-walnut update does the same right away, open-walnut update --check only reports, and open-walnut doctor carries the same line. A checkout you run from source is never asked to update (pull and build it yourself), and WALNUT_NO_UPDATE_CHECK=1 turns the check off.

Two channels are published: nightly is the newest commit on main that CI passed, every six hours, and latest is a tagged release, promoted each day from a nightly that has been out a day. npm install -g open-walnut@nightly switches an install to the nightly channel; it then follows nightly until you install @latest again.

If Claude Code is already configured on your machine, you can ask it to install and verify Open Walnut. Paste this into an authenticated Claude Code session:

Set up Open Walnut for me: read and run the skill at
https://github.com/EvanZhang008/open-walnut/blob/main/skills/setup-walnut/SKILL.md

The skill mirrors your existing provider setup, installs dependencies, starts Walnut, and verifies the connection with a real model request. Review the setup skill for the exact steps.

Choose a working directory, describe the work, and start a Claude Code session. The task stays attached to the session while its output streams in the browser.

Chat with Claude Code, change its mode or model, open a terminal, browse files, inspect history, and fork the session without leaving the page.

The home page combines tasks, Walnut, and Claude Code session columns. You can move between planning, execution, and review without rebuilding context in another app.

Move pinned tasks between Focus, Satellite, and Wait to show what needs attention now, what can run in parallel, and what is blocked.

Write Markdown notes with wiki links and backlinks. Walnut can search notes and memory through local keyword and vector indexes.

Open the Changed view to inspect the files edited by one session. Select code or leave line comments, then send the review back to that session.

Open Walnut uses the same session system for local and remote work. A small daemon on each host owns the long-running Claude Code processes, while the web app connects to those daemons.

• A session keeps running if the browser, SSH tunnel, or Walnut server disconnects.
• When Walnut reconnects, it finds the existing process and restores its history from the on-disk session log.
• Walnut deploys and updates its daemon over SSH. No manual copy step is required.
• Chat, terminal access, files, diffs, commands, and skills work on remote hosts.
• The host needs passwordless SSH and Claude Code; see what the remote host needs for the rest.

Add remote hosts to ~/.open-walnut/config.yaml:

hosts:
  my-server:
    hostname: dev.example.com
    user: myuser
    # Optional: identity_file, port, shell_setup

See Remote sessions via SSH for the full setup.

The Changed view reconstructs a diff from the selected session's own history rather than the repository's current Git state. This keeps edits attributed to the correct session when several sessions share a repository.

• View changes as a split or unified diff.
• Select code and ask the session about it.
• Add line comments and send them as one review.
• Group changes by repository when a session works across several repositories.

Open Walnut also displays dynamic Claude Code workflows as a live graph. Each node shows a subagent's status, model, token use, and duration. Select a node to read its transcript or inspect the script that created the workflow.

The graph is restored from its on-disk manifest after a reload or reconnect.

Tasks are the main unit of work in Open Walnut.

• Projects group related tasks; unassigned tasks stay in the Inbox.
• Tasks can contain subtasks, priorities, due dates, dependencies, tags, and notes.
• Session activity updates task progress, while final completion remains a human decision.
• The task board supports search, filters, bulk actions, and drag-and-drop ordering.
• Optional plugins provide two-way sync with Microsoft To-Do and Jira.

The notes workspace supports Markdown, [[wiki-links]], backlinks, folders, attachments, slash commands, and rich editing. Notes remain ordinary files under ~/.open-walnut/notes/.

Walnut can search your notes, and notes/AGENTS.md can provide shared instructions to Claude Code sessions.

Walnut records useful context in daily logs, project memory, repository memory, and session summaries. A background consolidation job updates topic pages so important context remains easy to find without loading every old conversation.

Search combines BM25 keyword matching, local vector embeddings, optional reranking, and freshness weighting. Memory, notes, tasks, and sessions use separate indexes so one source does not overwhelm the others.

• Routines: Run one-time, interval, and cron-based jobs from the Routines page.
• Custom agents: Create focused agents with separate conversations and memory.
• Commands and skills: Browse and run local or remote Claude Code commands and skills from the web app.
• Task integrations: Sync Microsoft To-Do and Jira through built-in plugins.
• Custom plugins: Install trusted Git or npm Plugins that add server logic, a native React App, Tools, Skills, Commands, Hooks, Agents, Providers, routes, and task sync without changing Walnut.
• Notifications: Send optional Slack notifications for important events.

A plugin App joins the same App Registry as Walnut's own screens, so one walnut.ui.app registration gives it a Sidebar entry, the route /apps/<plugin-id>~<app-id>, deep links, a badge, and a Command Palette entry. Installing a plugin means trusting its code: a server entry is full Node, and a native web entry shares the console's React tree.

After the author packages reach npm, the whole first authoring loop is one command, which scaffolds, links into the running console, and reloads on every save. They are not published yet; the guide gives the equivalent local-checkout command available today.

npx @open-walnut/plugin-cli new my-plugin --dev

Read Plugin development for the full guide, and examples/plugins/walnut-demo (the Walnut Plugin Demo) for a runnable example of every public capability. The console also ships a guided onboarding page at /plugins/new.

The beta SwiftUI app provides access to tasks, notes, and live sessions from an iPhone. It is not on the App Store yet: build it with Xcode from ios-native/. It pairs with the web app by QR code, and the QR carries the device token every request from the phone sends. The phone can reach your machine three ways, and one pairing covers all of them: the same Wi-Fi, a Tailscale tailnet (Settings › Phones & Cloud walks you through installing Tailscale on the machine and the phone, step by step, and offers a Tailscale QR; this works from anywhere while the machine is on, with no server to run), or an optional self-hosted cloud companion that also answers while the machine sleeps. The app learns every address after it connects once and switches to the best one that answers.

See Phone connection routes for how the switching works, and Cloud sync for the companion.

• Core app data is stored locally under ~/.open-walnut/.
• The server answers without a credential only to the machine it runs on. Any other device, including one on the same Wi-Fi, needs a paired device token. From another computer, forward the port over SSH (ssh -L 3456:localhost:3456 <host>). A reverse proxy in front of Walnut must send X-Forwarded-For.
• Open Walnut does not include telemetry or require an Open Walnut account.
• Model prompts are sent only to the provider you configure.
• Remote sessions connect only to hosts you configure.
• Cloud access, task integrations, Slack, and Git remotes are optional.
• Private plugins stay outside the repository.

Sessions open as columns on the home page. Legacy /sessions?id=... links redirect there automatically.

Walnut's own screens and every plugin App live in one App Registry, so they share the same Sidebar order, visibility, badges, and navigation. Home's Chat, Todo, and Agenda are Dock controls inside Home rather than separate apps.

Both walnut and open-walnut invoke the same CLI.

walnut web [--port 3456]             # Start the web app
walnut add "Task title" --project X  # Create a task
walnut tasks [--status todo]         # List tasks
walnut projects                      # List projects
walnut done <id>                     # Complete a task
walnut sessions                      # List sessions
walnut start <task_id>               # Start a Claude Code session
walnut recall "query"                 # Search memory and tasks
walnut tools list                    # List the operations sessions and agents call
walnut tools call <op> '{json}'      # Run one operation and print its JSON result
walnut logs [-f] [--json]            # Read structured logs

There is no chat subcommand: claude is the terminal REPL, and walnut tools call is the one-shot.

Use walnut --help for all commands and options.

Configuration is stored in ~/.open-walnut/config.yaml. The Settings page covers model providers, search, integrations, repositories, session hosts, usage, and other app options.

Open Walnut supports Anthropic, AWS Bedrock, OpenAI-compatible APIs, Google Generative AI, and Ollama. See Getting Started for provider examples.

src/
  model/          # Single model calls, provider adapters, and the model catalog
  ops/            # The operation registry sessions and the CLI both call
  commands/       # CLI commands
  core/           # Tasks, memory, search, sessions, routines, and config
  integrations/   # Built-in task integrations
  logging/        # Structured logging and redaction
  providers/      # Claude Code sessions, daemons, and subagents
  web/            # Express server, REST API, and WebSocket handlers
web/              # React web app
ios-native/       # SwiftUI companion app
infra/            # Optional cloud companion infrastructure
docs/             # Design, decisions, investigations, and references
tests/            # Unit, integration, end-to-end, and browser tests

Read Architecture for the system design and the documentation index for deeper technical documentation.

npm run build                       # Build the server and session daemon
cd web && npx vite build            # Build the web app
npm run dev                         # Watch the server
cd web && npx vite                  # Run the web app with hot reload
npm run test:quick                  # Run the default fast test suite
npm run test:focus -- <test-path>   # Run focused tests
npm run lint                        # Type-check the server

The backend development server and Vite can also be started together with:

npm run web:dev

• Node.js, Express, TypeScript, and SQLite
• React, Vite, and TypeScript
• Anthropic Claude and other configurable model providers
• Claude Code CLI with stream-JSON I/O
• Built-in hybrid search: SQLite FTS5 keyword lanes plus local vector rescore
• Vitest and Playwright

Contributions are welcome. Read CONTRIBUTING.md before opening a pull request.

LINUX DO

MIT