Karea Connect Alpha

Open a real terminal from any task and work on it with Claude Code, Codex or OpenCode. They run on your own machine (a laptop, a PC, a server you rent), signed in with your own accounts, exactly as if you had opened them in a terminal there. Karea shows that terminal in a floating window that stays open while you move around the app.

Karea never runs your code and never sees your AI accounts. It only connects your browser to your machine.

Part of the Max plan. On other plans the Run button, Connect and Settings → Karea Connect show greyed out with a Max pill and lead to the plans. Machines you paired stay paired: they connect again once the plan includes it.

You need Node 20 or newer on the machine (Linux, macOS or Windows). Go to Settings → Karea Connect → Pair a machine and run the command shown there, for example:

npx -y karea-connect@0.4.9 pair --server https://karea.app --code ABCD-EFGH --workspace ~/code

• The code works once and for 10 minutes.
• Each --workspace is a folder the terminal may open. Nothing outside those folders can be chosen from Karea.
• You choose a machine passphrase there. Keep it: you type it in the browser to open a terminal on that machine.

Then start it with the run command shown there. It reconnects by itself after a network drop or when Karea restarts. To keep it running in the background and after a reboot, install it once: npm install -g --prefer-online karea-connect@0.4.9 && karea-connect install-service (systemd on Linux, launchd on macOS; on Windows it prints the Task Scheduler command).

With tmux installed (Linux, macOS), sessions also survive the agent restarting. Without it they end when the agent stops; Settings → Karea Connect shows which mode each machine uses.

1. Open the Terminal app. Check Node: node -v must say v20 or higher. If not: brew install node (Homebrew from brew.sh).
2. Recommended: brew install tmux, so sessions survive the agent restarting.
3. Make sure the tool works there first: run claude (or codex, opencode) once and sign in. Karea starts exactly that program.
4. In Karea: Settings → Karea Connect → Pair a machine. Copy the first command and add one --workspace per folder you want to work in, for example --workspace ~/code/my-app. Paste it in Terminal and choose the machine passphrase when asked.
5. Copy the second command (run) and leave that Terminal window open. Settings → Karea Connect now shows your Mac as Online. For every day: install it as a service instead (third command), it then starts when you log in.
6. Open any task, click Connect, pick your Mac, the tool and the folder, type the passphrase. Claude Code opens in the floating window, already told which task to work on.

To stop it: close the Terminal window (or karea-connect uninstall-service). To remove the Mac from Karea: Settings → Karea Connect → Remove.

• The machine shows offline: the agent is not running, or cannot reach Karea. Look at its window (or ~/.config/karea-agent/agent.log when installed as a service on a Mac, journalctl --user -u karea-agent on Linux).
• A tool is missing from the list: the agent did not find it in its PATH. Run npx -y karea-connect@0.4.9 status in the same Terminal to see what it finds. A service keeps the PATH from when it was installed: reinstall it after installing a new tool.
• Wrong passphrase: nothing retries by itself. Each wrong try makes the next one wait longer: the 2nd wrong try 1 minute, the 3rd 5 minutes, the 4th 30 minutes, then 1 hour each time. The passphrase box counts down and opens again when the wait is over. The machine enforces it, even after a restart, and forgets wrong tries after a day without any. Forgot it? Remove the machine and pair it again with a new one.
• "Karea was updated since this page opened": reload the page.
• Typing does nothing: you may be scrolled back in the history; scroll down or press Esc.
• End a session from the machine itself: sessions run in tmux on the connector's own socket, so a plain tmux ls does not list them. List them with tmux -L karea ls, end one with tmux -L karea kill-session -t karea-… (on the Connect page, Stop from terminal gives you this command with the name filled in), or end them all with tmux -L karea kill-server. Without tmux, sessions end when the connector stops.
• Run the connector without a window: start it inside tmux, detached: tmux kill-session -t karea-connector 2>/dev/null; tmux new-session -d -s karea-connector "npx -y --prefer-online karea-connect@0.4.9 run --replace". Look at it with tmux attach -t karea-connector (leave with Ctrl+B, then D); stop it with tmux kill-session -t karea-connector.
• Stop the connector: Ctrl+C in its window, or pkill -f karea-connect. Installed as a service, it starts again by itself: remove it with karea-connect uninstall-service. Stopping the connector does not end sessions running in tmux; they are there again when it starts.
• Update the connector: Karea shows an Update button when a new version is out, with the command for how yours runs. It comes from npm (karea-connect@0.4.9): started with npx, starting it again gets the latest; installed with npm, run karea-connect update.
• "Karea Connect is not set up on this server": the relay is not configured on this Karea server yet.

• On a task (side panel or full page) click Connect, next to the deadline and activity readings at the top. Pick the machine, the tool and the folder. For Claude Code and Codex, Karea can start them with "Work on Karea task KA123: title" as the first message, so with the Karea MCP connected they read the task first.
• Type the passphrase the first time. Tick Remember in this tab to not be asked again until the tab closes.
• The window floats over every page. Drag it by its title bar, resize it from the bottom-right corner, open more tabs with +, and collapse it to a small pill with −. When a tool rings the terminal bell (for example Claude Code waiting for your approval) while the window is collapsed, the pill pulses and Karea shows a notification.
• The keyboard button shows Esc, Tab, Ctrl-C, arrows and Enter: useful on a phone.
• Scroll up with the mouse wheel to see earlier output; scroll back down, or just start typing, to return to the program. Hold Shift (Option on a Mac) while dragging to select text to copy.
• Closing a tab does not stop anything: the session keeps running on the machine. Reopen it from the task (Related → AI sessions, or Connect → Open) or from the Connect page, even after a reload or from another device.
• Closing the window: its × asks what to do. Close, keep it running (the usual choice) just hides it: continue later from the Connect page or the task. End the session stops the tool on the machine. − minimises the window to a small pill instead.
• Resume an ended Claude Code session: Resume starts it again with its whole conversation (claude --resume), in the same folder or worktree. Needs the machine online. Codex and OpenCode sessions cannot be resumed from Karea yet.

Every session shows in the task's history (started, ended and how long it was on screen), in the Recap, and in Reporting → Time in Karea Connect.

Run, next to Task at the top of the sidebar, opens the Connect page: every Karea Connect session in one place.

• Filter by project (or All projects). The list shows the task, the tool, the machine, the worktree branch, whether it is running or ended, and when it was last used.
• Click a session to read its conversation on the right. A running one is live: write to Claude and answer its prompts right there. An ended one is read-only, with Resume at the top.
• Pop out: moves a running session into the floating window, which stays with you while you move around Karea. The page then says Session running in the floating window, with Bring back here (closes the window's tab and shows the chat on the page again) and Show the window.
• New session starts one from here; link it to a task (optional) by searching in the launcher, or leave it unlinked.
• Names and archive: a session is named after the title Claude Code gives the conversation (kept in this browser, like the conversation); click the name to give it your own. Archive hides an ended session from the lists; Archived at the top shows them, with Unarchive.
• Default folder per project: the first time you start a session for a project's task, switch on Default folder for <project>. From then on that folder is picked for every task of the project on that machine. Change it in Projects → Karea Connect.
• The task card on top shows where the task stands (status, priority, deadline, subtasks), what it is about (its AI summary or description), its latest note and its Connect time. Fold it to one line with the arrow; Open task opens the task in the side panel without leaving the page.
• History when the machine is off: conversations are read from your machine, so they need it online. Each time you read one, this browser keeps a copy (the last 20 sessions), and shows it when the machine is offline. Only this browser has that copy; Karea never stores conversations.
• Every Claude Code session can be read here, in chat or terminal view. Codex and OpenCode sessions have no conversation to show, and neither do Claude Code sessions started by a connector older than 0.3.0.

A worktree is a second checkout of the same Git repository, on its own branch, in its own folder. Two sessions in two worktrees never touch each other's files.

• In Connect, open Folder and pick New worktree in …. Karea suggests a name and a branch from the task (karea/ka123-title); From is the branch to start from (the current one if empty).
• It is created in .karea-worktrees/ inside the project and hidden from git status. Existing worktrees show in the same list, under their project folder.
• A task usually keeps one worktree for all its sessions: the launcher picks the task's latest worktree by default. Create as many as you like with New worktree in ….
• The launcher checks the name and branch before starting (a name already taken, a branch already open in another worktree). If Git still refuses, the window says why in plain words (not a Git repository, no commits yet, unknown From branch, no write access) and offers Change the worktree (back to the launcher, filled in) or Start without a worktree.
• A task lists its worktrees under Related → AI sessions: start a new session in one, or delete it. Deleting asks you to type the worktree's name (with a Copy button), after 5 seconds to read what happens: the folder and any uncommitted work in it are gone; the branch and its commits stay. A session still running in it has to be ended first.
• Don't ask me again in that dialog (after one more warning) deletes worktrees right away from then on, uncommitted work included. Turn the warning back on in Settings → Karea Connect.

• At the start (with Brief … on the task on): Claude Code, Codex and OpenCode get the task ID, title and a short summary, and are told to read the whole task (description, notes, AI context) with the Karea MCP, keep its AI context current and add notes as they go.
• The Karea MCP on the machine is what makes that real. Without it the AI only knows the title and summary and cannot write back. The connector checks each tool's set-up; when it is missing, Connect shows the command to add it (and, for Claude Code, the Karea skill).
• Linked automatically: every Claude Code session started from a task is linked to it, so what it writes to Karea is attributed to that session.
• Summary at the end (optional, Settings → Karea Connect): when you end a Claude Code session from Karea, Claude first adds a note to the task with what was done, the decisions and what is left.
• Karea itself records when each session ran, on which machine and for how long (task history, Recap, Reporting), never the conversation.

A Claude Code session can be shown as a conversation instead of the raw terminal. Pick Chat when you open it, or switch any time with Chat / Terminal in the window's title bar. Both show the same session.

• A plain, dark conversation: your messages and Claude's replies one under the other, formatted. Events (thinking, compaction, background tasks finishing, interruptions) are grey lines with a dot.
• Every tool call (command, file, search) is a card that opens to show the details and the result: green border when it worked, red when it failed, amber while it waits for you.
• Permission prompts appear as a card: Allow, Decline (optionally telling Claude what to do instead) or Answer in the terminal.
• Claude's questions appear with their options as buttons, several when it asks for more than one, plus a box for your own answer.
• Type below to send a message (Shift+Enter for a new line). Stop interrupts Claude, like Esc in the terminal.
• When the window is collapsed and Claude is waiting for you, the pill pulses and Karea notifies you.

It works by reading the conversation file Claude Code keeps on your computer and by Claude Code's own hooks, added only to sessions Karea starts. Like the terminal, it is end-to-end encrypted. While the chat is not open, Claude asks in the terminal as usual. Codex and OpenCode are shown as a terminal only.

Everything Karea Connect puts on a machine lives in one folder in your home directory (~/.config/karea-agent), plus its sessions in tmux and its background service. On macOS or Linux, in a terminal on that machine:

1. End every session Karea started (they run in their own tmux server, separate from yours): tmux -L karea kill-server
2. Stop the connector, however it was started (tmux, a window or the background service): tmux kill-session -t karea-connector 2>/dev/null; karea-connect uninstall-service 2>/dev/null; pkill -f "karea-(connect|agent)"
3. Uninstall it, if you installed it with npm install -g: npm uninstall -g karea-connect karea-agent
4. Delete its files: the pairing and keys, logs, settings and the chat hooks (and the dev copy, if you made one): rm -rf ~/.config/karea-agent ~/.config/karea-agent-dev
5. Remove the machine in Karea: Settings → Karea Connect → Remove. Its token stops working at once.

Worktrees Karea created stay in your projects, as .karea-worktrees folders with their karea/… branches: delete them from the task (Related → AI sessions) or with git worktree remove. Claude Code's own conversation history (~/.claude) belongs to Claude Code and is not touched.

On Windows: end the connector's window, run schtasks /Delete /TN "Karea agent" /F if you installed the service, npm uninstall -g karea-connect karea-agent, and delete %USERPROFILE%\.config\karea-agent.

On the Connect page, the power button (Stop Karea Connect on my machine → Remove it completely) gives you these commands ready to copy.

• End-to-end encrypted. Everything typed and shown is encrypted between your browser and your machine with a key made from the machine passphrase. Karea and its relay only pass along data they cannot read, and store none of it.
• Your Karea password alone is not enough. Someone who gets into your Karea account still needs the machine passphrase, and each wrong try makes the machine wait longer before the next (up to 1 hour).
• Only a signed-in browser can open a terminal or add a machine: API keys and connected AI apps cannot.
• Only Claude Code, Codex and OpenCode can be started, in the folders you listed. A plain shell is only offered if you start the agent with --allow-shell.
• Settings → Karea Connect → Remove cuts a machine off at once.

As with any website, the passphrase is typed into a Karea page: use a passphrase you do not use anywhere else.