What Is Ravenry? The Beginner's Guide to the Local Board for Claude Code and Codex Sessions
CodexFuse Team · 2026-11-05T07:48:24.854Z · 17 min read min read
What Is Ravenry?
Ravenry is a free, open-source local board that puts every Claude Code and Codex session on your Mac on one page, sorted by what needs you. It is a small Node program you install with npm, and it watches Ravenry Claude Code sessions through two hooks, then shows each session's state, live screen, and context fill on a board at localhost:4600. You answer questions, pick menu options, and attach files from the board instead of hunting through terminal tabs.
The problem Ravenry solves is simple to state and hard to live with. When you run several Claude Code sessions at once across different projects, the session that needs you is buried in a tab you are not watching, and the same question comes up again in the next session. Ravenry was built by Simon Patole while he was running many Claude Code sessions at once building Antics, and the README says following them all was the hard part: finding the tab that was waiting, answering the same kind of question again, and telling each new session what the last one already knew.
The board is local-only, with no telemetry of any kind, and it runs only while its terminal is open. There is no login item and no background service, so closing the terminal stops the board, and starting it again is one command. Before you run any agent against a real project, it is worth checking the values you will hash or sign in your integrations with a SHA-256 hash generator, and worth knowing that the servers behind an agent setup like this usually run on VPS hosting.
How Do You Install Ravenry?
Learning how to use Ravenry starts with two commands, and the whole install takes a few minutes on a Mac with Node 22 or newer. The board needs macOS, Node.js 22 or newer, and Claude Code with claude on your PATH, with Codex as an optional second agent. You install the Ravenry npm package ravenry-app globally, then run ravenry once, and the first run walks you through setup.
Getting Ravenry running takes five steps:
- Install the package globally with npm i -g ravenry-app, which puts the ravenry command on your PATH.
- Run ravenry, which runs ravenry setup the first time and checks your Mac for macOS, Node, claude on your PATH, and the terminal you are in.
- Answer the setup questions: in iTerm2 it offers a small Python folder so the board can pick menu options, and it shows the exact lines it would add to ~/.claude/settings.json before writing anything.
- Say whether rule suggestions should turn on, knowing they stay off unless you say yes.
- Wait for the Ravenry localhost 4600 board to open in your browser, then start claude in a project folder and watch it appear on the board within a few seconds.
The npx route exists for a first look, but the README warns against relying on it. Running npx ravenry-app works once, yet setup does not install the hooks from it, because npx keeps its copy in a cache it may clear and a hook needs a path that stays put. Install it globally to keep it, and use ravenry doctor when anything looks wrong, since that command says what works and what does not in plain words.
| Command | What it does |
|---|---|
| ravenry | Start the board on localhost:4600 and open it, running setup the first time |
| ravenry setup | Check this Mac and install the Claude Code hooks, and the Codex hooks when Codex is installed |
| ravenry doctor | Say what works and what does not, and what to do about each |
| ravenry uninstall | Take Ravenry's hooks out of settings.json, and out of the Codex files, backing up first |
| ravenry uninstall --purge | Also delete the ~/.ravenry data folder |
| ravenry --version | Print the version |
What Does Ravenry Change on Your Mac?
Ravenry changes very little on your Mac, and setup shows you every change before it makes one. The main change is two hooks in ~/.claude/settings.json, which setup adds only after showing the exact lines and asking first, and it backs the file up before touching it. Your other hooks and settings stay exactly as they are.
| Hook event | Command | What it does |
|---|---|---|
| SessionStart, SessionEnd, UserPromptSubmit, Notification, Stop | hooks/events.mjs | Writes one line per event to ~/.ravenry/events/ and tells the board |
| Stop | hooks/handoff-stop.mjs | Asks a session past half context to write a hand-off at its next clean point |
If Codex is installed, setup offers the same two hooks in ~/.codex/hooks.json, with --assistant=codex, plus the trust entries Codex needs in ~/.codex/config.toml, all in one marked block. Setup shows those lines and asks first, and it backs both files up, while other hooks such as cmux's stay as they are. The data folder ~/.ravenry/ holds your projects, briefs, ideas, hand-offs, hook events kept for 14 days, and phone access and alert settings.
Only in iTerm2, and only if you say yes, setup adds a small Python folder at ~/.ravenry/iterm2-py and a board tab profile in the iTerm2 DynamicProfiles folder. Nothing else changes: no login item, no background service, and the board runs while its terminal is open. To remove Ravenry completely, run ravenry uninstall --purge and then npm rm -g ravenry-app.
What Does the Ravenry Board Show You?
The Ravenry session board groups every project by what needs you, so the sessions waiting on an answer sit at the top with their question visible. Each project becomes a card when you start claude in its folder, and the board shows each session's state, live terminal screen, context fill, and memory. A new board starts empty, and a session shows up within a few seconds of starting.
| What the board shows | Where it comes from |
|---|---|
| Session state, grouped as Needs you, Working, Waiting on others, or Idle | Hook events reported from your Claude Code and Codex settings |
| Live terminal screen, with a full-screen view | The board reads each session's screen in cmux or iTerm2 |
| Context fill for each session | Each session's context use, shown beside its state |
| Project memory | Briefs, hand-offs, and rule suggestions carried between sessions |
The live screen is the part that saves the most tab-hunting, since you can read what a session is doing without switching to its terminal. In cmux and iTerm2 the board reads the screen and types into it, while sessions in any other terminal are watch only. The full-screen view opens one session large when you need to read a long output.
How Do You Answer a Session from the Board?
Answering from the board is the feature that separates Ravenry from a dashboard that only watches. When a session stops on a question, you reply in text, pick a menu option such as Yes or No, or attach a file, all from the session's card. You can also open the session's tab or close idle sessions without leaving the board.
Menu answers work in cmux and iTerm2, where the board can type into the session, and iTerm2 needs its Python API switched on for them. The board asks nothing extra for this: the same two hooks that report events also carry your answer back through the terminal. If a session runs in Terminal, VS Code, Ghostty, Warp, or tmux, you see its state and question on the board and answer it in its own window.
If you have not used the agent itself yet, start with how to use Claude Code, then add Ravenry once you have more than one session to watch. The board adds the most value exactly when one session is no longer the whole story, and a single session in a single terminal needs no board at all.
How Does the Half-Context Hand-Off Work?
The half-context hand-off is Ravenry's answer to the oldest problem in long agent sessions: a session that has used most of its context starts forgetting, repeating, or drifting. When a session passes half its context, the Stop hook asks it to write a hand-off at its next clean point, and a fresh session picks that hand-off up. You lose nothing mid-thought, because the hand-off waits for a clean point instead of cutting the session off.
The hand-off is a short written summary, and it lives in the data folder with your briefs and ideas, so the next session starts with what the last one knew. The README is clear that neither hook ever blocks a session, and the board settings can turn the hand-off off entirely. Half context is the trigger the README names, and the hand-off happens at the next clean point, not in the middle of a thought.
The arithmetic is simple: half context means 50 percent of the context window, so a session hands off once it has used half of what it can hold. Hook events are kept for 14 days, which gives you two full weeks of session history to look back through. Four alert channels cover the phone side, and the next sections cover each of these pieces in turn.
What Are Project Briefs, Plans, and Rule Suggestions?
Briefs, plans, and rule suggestions are the three ways Ravenry carries what you said into the next session. A project brief is a short note per project with its goal, plan, next step, and notes, and the board keeps a gallery of the last pictures each session showed you. Plans with gates let you hand work over as a plan with steps, which runs on its own and stops at the gates you set.
Rule suggestions watch for corrections you keep typing in your sessions and offer them as rules for your CLAUDE.md, or AGENTS.md for what you told Codex. They stay off until you turn them on, and when they are on, they send the messages you typed once a day to your own Claude or Codex login to find the corrections you keep repeating. That daily send is one of only two things that ever leaves your Mac, and the privacy section below names the other one.
How Does Ravenry Work on Your Phone?
The phone view is the whole board on your phone, reached by scanning a QR code from the phone button at the top of the board. A phone on the same Wi-Fi gets the board live, with alerts when a project starts needing you, so you can step away from the desk and still answer. The alerts arrive through Telegram, Discord, Slack, or ntfy, plus Mac notifications on the Mac itself.
Phone access works on your home network only, and the README states that limit plainly. The board answers to the Mac itself and to your local Wi-Fi address, each phone needs the key in the code, and choosing New key signs every phone out. The first time a phone connects, macOS may ask whether Node may accept incoming connections, and you allow it for phones to reach the board.
That home-Wi-Fi-only limit is a design choice, not a bug to work around with port forwarding, and the README never suggests exposing the board to the internet. Treat the board as a household tool: anyone on your Wi-Fi with the key can see your sessions, so keep the key private and rotate it with New key when someone leaves.
Which Terminals Can Ravenry Answer In?
Ravenry answers sessions in cmux and iTerm2, and watches sessions everywhere else. In those two terminals the board reads each session's screen and types into it, which is what makes answering from the board possible. In iTerm2, menu options need the Python API switched on, in iTerm2 Settings under General, Magic, Enable Python API, and macOS may ask once to let the board control iTerm2.
Where you start ravenry decides where its page opens. In a cmux tab the board runs in that tab and its page opens in a cmux browser pane above it, while in an iTerm2 tab a Ravenry tab opens with the page on top and the board's terminal below. Anywhere else, the board runs in your terminal and the page opens in your browser, and you keep the window open, since Ctrl+C stops the board.
Sessions in Terminal, VS Code, Ghostty, Warp, tmux, or any other terminal are watch only: you see their state, questions, and context, and you answer them in their own window. That split is worth knowing before you install, because the board is most useful when your sessions already live in cmux or iTerm2.
Ravenry vs ccdeck: What Is Different?
ccdeck is the closest comparison, because it is also a free, open-source local dashboard for Claude Code and Codex sessions. The install guide by ccdeck's own builder describes it as one local page with every session on the machine, sessions waiting on you at the top, every subagent and tool call live, and cost and quota beside them. The difference is what each board lets you do with a waiting session, and which machines each one runs on.
| Feature | Ravenry | ccdeck |
|---|---|---|
| Answer from the board | Yes, in cmux and iTerm2: reply, pick menu options, attach files | Its hook only forwards events, so you answer in the terminal |
| Platforms | macOS only | macOS, Linux, and Windows, plus a desktop app |
| Install and port | npm i -g ravenry-app, board on localhost:4600 | npx ccdeck, deck on 127.0.0.1:4317 |
| Hooks in Claude Code settings | Two hooks | Ten hook entries per event, up to twelve on newer Claude Code |
| Subagent and tool-call detail | Live screen per session | Each subagent gets its own card with live tool calls |
| Cost and quota display | Not stated in the README | Cost and quota shown beside each session |
| Telemetry | None of any kind | Usage reports sent to api.ccdeck.dev, with an opt-out flag |
| Hand-off at half context | Yes, automatic | Not stated in the guide |
| Phone access | Whole board on home Wi-Fi via QR code | Local network access with a private key |
The choice comes down to two questions: which machine you run on, and whether you want to answer from the board. Ravenry is the pick when you work on a Mac in cmux or iTerm2 and want to reply without switching windows, while ccdeck is the pick when you work on Linux or Windows, or want per-subagent tool calls and cost tracking. Both are free and open source, both stay local, and both watch Codex beside Claude Code, so the wrong choice costs little: try one, and switch if the other fits better.
Other names in the same space include Session Relay MCP, Mallard, and claude-code-ui, which this guide names once and does not review. A third shape exists for people who want to run agents in parallel rather than watch them: Paradev is an execution workspace, and how to use Paradev covers it, while Ravenry and ccdeck are oversight boards.
What Are Ravenry's Limits?
Ravenry is two days old, and its limits read like a young project's limits. It runs on macOS only, it needs Node.js 22 or newer, and it needs Claude Code installed, with Codex as an optional second agent. The repository was created on November 3, 2026, and by November 5 it had 11 commits, 3 stars, and no releases, which is the shape of a brand-new project rather than an established one.
Codex support is narrower than Claude Code support in four named ways: no pictures, no background tasks, no Close idle on the Sessions page, and no recaps. Outside cmux, Codex sessions are found by folder or shown watch only, and Codex support was measured on version 0.166.0, so newer Codex versions may behave differently. The board has no runtime dependencies and no build step, which keeps it simple, and also means there is no hosted version, no Windows or Linux build, and no account to recover if your Mac dies.
When your sessions run in hosted sandboxes instead of on your Mac, the oversight problem changes shape, and how to use E2B explains the cloud sandbox side. Ravenry watches what runs on your own machine, and that local focus is both its strength and its boundary.
Who Should Use Ravenry, and Who Should Not?
Ravenry fits a Mac developer who runs several Claude Code or Codex sessions at once and keeps losing the one that needs an answer. If your sessions already live in cmux or iTerm2, if you want a half-context hand-off without thinking about it, and if you like tools that stay local with no telemetry, it is worth an install. The whole setup is two commands and a few questions, and ravenry uninstall --purge removes it cleanly if it does not fit.
It does not fit everyone yet. Skip it for now if you work on Windows or Linux, if your sessions live in Terminal or tmux and you want to answer from the board, or if you need per-subagent tool calls and cost tracking, which ccdeck already shows. Early adopters should also expect fast change: the features and version numbers here describe Ravenry as of November 5, 2026, one day after its Show HN launch, and a two-day-old project can change quickly.
Sources
Ravenry README, GitHub patoles/ravenry, fetched November 5, 2026. The README is the source for the install commands, the two hooks, the board groups, the half-context hand-off, the phone access rules, the requirements, and the privacy claims in this guide.
Vibehacker news digest, Ravenry puts every Claude Code and Codex session on your Mac on one local board, November 4, 2026, fetched November 5, 2026. The digest confirms the Show HN date, the Apache 2.0 license, the npm install, the localhost:4600 board, and the home-Wi-Fi-only phone access.
ccdeck install guide, DEV Community, by Bargan Constantin, checked against ccdeck 3.38.0, fetched November 5, 2026. The guide is the source for ccdeck's one-command install, its ten hook entries, its one-way hook, and its desktop app.
ccdeck homepage, ccdeck.dev, fetched November 5, 2026. The homepage lists version 3.81.3, the free open-source AGPL-3.0 license, the macOS, Windows, and Linux installers, and the per-subagent tool-call and cost display used in the comparison table.
Show HN launch thread, November 4, 2026, as reported by the vibehacker digest, fetched November 5, 2026. The direct thread page returned an error when fetched for this guide, so the launch date and Show HN placement are cited through the digest rather than the thread itself.
Frequently Asked Questions
Is Ravenry free to use?
Yes. Ravenry is free and open source under the Apache 2.0 license, and the board has no runtime dependencies and no build step. You install it with npm, there is no account, and there is no paid tier named in the README.
How do I install Ravenry?
Run npm i -g ravenry-app, then run ravenry, which runs setup the first time. Setup checks your Mac, shows the exact hook lines it would add to ~/.claude/settings.json, asks before writing anything, and opens the board at localhost:4600.
Does Ravenry work with Codex as well as Claude Code?
Yes, with narrower support. Codex sessions show up beside Claude Code's, with their state, live screen, context, alerts, replies, and menu answers from the board, plus the half-context hand-off. Pictures, background tasks, Close idle, and recaps are not shown for Codex, and support was measured on Codex 0.166.0.
Can I answer sessions from my phone?
Yes, on your home Wi-Fi. Scan the QR code from the phone button on the board, and the whole board opens live on your phone, with alerts through Telegram, Discord, Slack, or ntfy when a project needs you. The board answers only to the Mac itself and its local Wi-Fi address, so it does not work away from home.
How is Ravenry different from ccdeck?
Ravenry lets you answer from the board in cmux and iTerm2, adds only two hooks, and carries automatic half-context hand-offs, but it runs on macOS only. ccdeck runs on macOS, Linux, and Windows with a desktop app, shows each subagent's live tool calls and cost, but its hook only forwards events, so you answer in the terminal.
