Setting up Even Keel
The README has the quick start. This page is the rest, in the order a new installation meets it: installing, the first start, a project, its tracker, the page on other devices, the service, updates and removal. Every variable and key is in the reference.
- Installing — what it needs, from npm or from a clone, and a look at the page on fake data
- The first start — the setup’s steps: git, the agent and its account, the demo
- Projects — the wizard, the repository’s folder or address, what a project needs
- Trackers and plugins — the built-in tracker, a profile per tracker, packages for sessions, CI and token permissions
- The page — answering from the phone, reaching the page from another machine
- As a service — npm, a clone, Windows, Linux and macOS, a machine of a hub
- Updating — from the page or by hand, plugins, stored state, going back
- Uninstall — and what stays on the machine
- The CLIs it depends on — what Even Keel relies on in each agent’s CLI, and the checked versions
Installing
Section titled “Installing”For a server or NAS with Docker, see Installing with Docker.
The README’s quick start installs Even Keel with npx even-keel (npx.cmd even-keel on Windows, why), which also sets it up as a service: the details are in Installed with npm. To run it in a terminal instead of as a service:
npm install --global even-keeleven-keelThe other way is a clone of the repository.
What it needs
Section titled “What it needs”- Node.js 24 or newer (nodejs.org; on Linux nvm needs no
sudo). On macOS the nodejs.org installer leaves npm’s global folder to root: move it into your home first, with the commandsnpx even-keelprints, and never usesudo. On Windows the MSI installer of Node can sit on “Preparing to install…” for over 10 minutes: wait it out. - An agent and an account of it: Claude Code, Codex, OpenCode (preview) or GitHub Copilot CLI (preview), on a subscription or an API key; OpenCode also runs its free models. The setup can download the CLI for you.
- git, recommended (git-scm.com), with your name and e-mail set (
git config --global user.nameanduser.email): sessions commit and merge under that name, and the Git step of the setup sets both. Without git a project is a plain folder: A project without git. - A tracker, optional: a Huly workspace, GitHub, GitLab (GitLab.com or your own server) or Forgejo (Forgejo, Gitea or Codeberg) projects with Issues, a Linear workspace or a Jira Cloud site. Without one the tasks live in the built-in tracker.
- Windows, Linux or macOS. Windows is where it runs every day; Linux and macOS (Apple silicon) were checked end to end.
From a clone
Section titled “From a clone”A clone keeps its data and logs in its own folder and runs its sources:
git clone https://github.com/NamerekT/even-keel.gitcd even-keelnpm installnpm run buildnpm startThen open http://localhost:4747, as in the README’s quick start. To set the clone up as a service: below.
Do not run npx even-keel inside a clone: npx sees the clone’s own package.json, takes the package for installed and fails with “‘even-keel’ is not recognized” because node_modules/.bin is empty.
A look first, on fake data
Section titled “A look first, on fake data”The page with a made-up chain, no tracker and no sessions, after npm install; it opens at http://localhost:5173:
npm run dev:fakeThe first start
Section titled “The first start”The projects and the settings live in Even Keel’s database and are edited on the page; there is no file to create. The first start walks a short setup, each choice saved as you make it and changed later in Settings:
- the languages of the page and of the session prompts;
- git — whether it is installed (Even Keel never installs it and shows the command that does) and the name and e-mail commits are made as, written into git’s global config of the user Even Keel runs as;
- the agent all projects run on by default, its account (sign in, or add one in a dialog over the step) and, for each provider, whether sessions run on the CLI version Even Keel was checked on (downloaded with your consent, about 340 MB for Claude Code) or on the one installed;
- a tracker profile (or later);
- whether Even Keel may ask GitHub twice a day for a new release — nothing is asked until you answer;
- and the statistics.
A step is checked on the line only once it has its answer, and a step you skip is not offered again.
If you leave the setup unfinished, Add project (or Connect your own in the demo) first asks whether to finish it: Set up goes back to the step it stopped at, Not now leaves you where you are.
The Git step
Section titled “The Git step”Git is needed only for projects that live in a repository.
The setup’s Git step first asks Use git?: Yes goes on to the check of git and the name and e-mail for commits; No is for projects without git and goes on at once, asking nothing of git.
Where git is already installed, Yes is picked in advance.
The answer is what the project wizard starts on for a new project, each project still picking its own; change it later on the Git step or in Settings → Chain → New projects.
On macOS, the setup’s Git step always offers xcode-select --install, even when Homebrew is installed.
It installs only Command Line Tools; Xcode from the App Store is not needed. After installation, press Check again.
If full Xcode is already installed but its license has not been accepted, run sudo xcodebuild -license accept.
The macOS git stub reporting xcrun: error: invalid active developer path is treated as missing git; a license error remains a git command error with its original message.
The Agent step
Section titled “The Agent step”The setup’s Agent step has three parts: the agent cards, each saying only whether its CLI is installed and on which version; “Which version to run” for the chosen agent, Yours or Checked; and its accounts as a table, the one sessions run on checked, + Add in the heading.
Without your CLI, Yours shows the command that installs it and Check again.
Choosing Checked there or in Settings → Providers and models asks before downloading: the dialog shows the version and approximate size, and Cancel keeps Yours.
Blue bands under the header and in the agent’s block show downloaded bytes while it runs; in the setup, adding an account opens by itself once the download ends, since the sign-in goes through the CLI.
Next waits until the agent has something to run on (your CLI, or the copy, even still downloading) and an account.
A provider already on Checked whose copy is missing asks the same when you select it or add its account; closing the dialog keeps the choice and leaves the chain waiting.
No startup, sign-in or version check downloads a copy by itself, with one exception: a provider on Checked whose copy you have downloaded before fetches each newer checked version without asking again.
If downloading fails, CLI version switches to Yours for that provider and offers Try downloading again.
An installed CLI can then run sessions; without one, the block shows an installation command, Check again, and Checked to choose again.
Even Keel never installs a global CLI.
Old copies are removed, retrying folders still held by a process at startup and each version check.
Accounts
Section titled “Accounts”Installing a CLI or signing into it does not add an Even Keel account.
Use Add account on the setup’s Agent step, the Accounts page or the project wizard.
If a global Claude Code or Codex folder is already signed in, choose Use this sign-in to add it or Sign in with another account to keep a separate folder.
Without an existing sign-in the normal choices open directly.
The first account you add for a provider becomes its shared account.
Claude Code on Amazon Bedrock needs no sign-in, only AWS credentials the user Even Keel runs as can read: with the Windows service under another user, sign in to AWS (aws sso login, aws configure) as that user, or give the keys in the dialog (Bedrock accounts).
Google Vertex AI is the same: run gcloud auth application-default login as that user, or give a service account key file the user can read (Vertex accounts).
Microsoft Foundry’s Entra ID way needs az login as that user, or give the resource’s API key (Foundry accounts).
The demo
Section titled “The demo”With no project yet, the home page offers two ways: Watch the demo or Connect your own.
The demo takes about two minutes and needs nothing installed: Even Keel makes a small project folder in its state folder and a project DEMO on the built-in tracker, and its chain goes through three tasks while you watch — one waits for another, and one asks you a question in the session’s chat.
The folder follows the same rule as a new project (the Git step): a git repository, where each task is committed and merged, unless you answered No or git does not start on the machine — then it is a project without git, whose tasks write their files in the folder and close by their answer. Each Run again picks the mode anew.
The agent is a script, so no account is used and nothing is spent; the demo stays out of the launch chart and the statistics.
A band over the demo’s project leads to your own project; when the demo is over, its card offers to run it again or remove it.
It is never removed by itself: the project wizard’s Remove the demo (on by default) removes it once your project is added, and Remove in the band’s ⋯ stops it and deletes its project, tasks and folder at any moment.
Projects
Section titled “Projects”A project is a repository — or a folder without git — with a tracker to take tasks from and an agent to run them. The wizard that adds one checks each of these as you fill it in.
Then the page opens the wizard that adds a project.
You pick the agent of the project (the shared one unless you choose another; the wizard says whether it has a CLI and a signed-in account, and Add an account opens a dialog over it), give it the repository’s folder or address, pick a tracker profile (or add one right there) and the project in that tracker, which it suggests from the tracker’s list and, on GitHub and GitLab, from the repository’s remote (on GitLab, a remote on the profile’s server).
The wizard checks the repository and its main branch (it suggests the checkout’s current branch and offers the others; a branch the repository lacks is created when the project is added, and the checkout switches to the branch you name; a folder that is not a repository yet, or one with no commits, gets a button that runs git init and makes an empty first commit on that branch), the project in the tracker (it shows how many open tasks it sees), Claude Code’s trust in the folder (a task’s own run can give it to Claude Code whatever the project’s agent) and where tasks run — Own folder per task (a git worktree made for the task and removed after Done) or Permanent folders (a few folders a task switches the branch in).
All the steps are on one page, each marked once its check passes or with the reason under its field when it fails, and What will be created at the bottom sums the project up before Add project.
When you add the project, Even Keel checks the repository again before saving it.
The wizard shows a validation error under the field that needs correcting and marks its step in red. Empty required fields are named at the bottom of the form.
Leaving the project wizard and returning keeps the fields you changed yourself.
Untouched Git and tracker choices follow the current setup settings on each visit; a choice you made in the form takes precedence.
A failed check or add keeps your edits. Adding the project or reloading the browser page clears the draft.
The folder or the repository’s address
Section titled “The folder or the repository’s address”The repository need not be on the machine yet. A project in git has one field, Folder or repository address, and Even Keel works out from what you type what to do; a short line with an icon under the field says how it read it:
- An address —
https://…,ssh://…,git://…orgit@host:owner/repo.git— is a clone. Even Keel asks the remote right away, so a wrong address or a missing sign-in shows before you add anything. A private repository needs git on Even Keel’s machine signed in to that server as the user Even Keel runs as (its credential helper or an SSH key). An SSH server that user has never connected to is refused until its host key is accepted once: the wizard shows thessh -Tcommand to run in that user’s terminal. A main branch the remote lacks is created when the project is added. - The folder of a repository — a clone already on the machine — is taken as it is; the line names its remote, or says it has none. A folder inside a repository is refused with a button that puts the repository’s top folder into the field.
- A folder without git becomes a new repository: whatever it already holds goes into the first commit, except what its
.gitignorefiles leave out, and the wizard says how many files and how much that is. - A path that is not there — Even Keel makes the folder and a new repository in it; the line shows the full path, so a typo is visible.
- Just a name, such as
my-app— a new folder with a repository in Even Keel’s projects folder (projectsin its data folder), numbered if the name is taken.
A path must be full: a relative one such as ./my-app is refused, and so are a whole disk and the home folder.
A clone goes into the projects folder under a name it suggests from the address; type another name, or press another folder… for a full path anywhere.
A clone needs an empty folder or one that is not there yet.
If the projects folder already has a clone of the same remote and branch that no project uses, the wizard offers Use it.
A clone and a new repository need git’s name and e-mail for commits: without them the wizard says so under the field, and Set them asks for both in a window over the wizard, keeping everything typed.
The same button stands under the error if the creation window gets there, and the failed step is retried once they are saved.
A project without git takes a folder the same way as a clone, with no address.
The folder accepts ~ for the home folder of the user Even Keel runs as.
On Windows it also accepts environment variables such as %USERPROFILE%\Projects\example, with any letter case.
They come from Even Keel’s own environment: a service running as another user uses that user’s values.
Unknown or empty variables stay as typed; values are expanded once. $NAME and PowerShell’s $env:NAME are not expanded, and on Linux/macOS percent signs stay literal.
Checking, creating a repository and adding the project use the same expansion; the saved folder is absolute, so later environment changes do not move an existing project.
Adding the project
Section titled “Adding the project”Add project opens a window with the steps: the folder, the clone with its progress (and its Git LFS files, if it has any) or the first commit, the project itself, Claude Code’s trust and the project’s packages.
A step that fails says why and offers Retry; when only the Git LFS files fail — say, one was never pushed to the server — the clone is kept and Retry downloads just those files.
Cancel removes only what Even Keel made — a folder it created, or what it put into an empty one — and only until the project is saved; after that the project stays and the window offers Open the project.
What a project needs
Section titled “What a project needs”Each project needs:
- a git repository with a main branch —
mainunless the project names another inbranch; with a remote, Even Keel pushes it after every task; - for Claude Code in the background, Even Keel automatically marks the project’s checkout as trusted in Claude Code before each background launch or resume, using the selected account. On Windows it writes the forward-slash path Claude reads, copying an older backslash entry when needed and preserving the original. Its task worktrees inherit that trust. This also enables repository hooks. The Agent SDK and other agents do not write Claude trust;
- for Codex, Even Keel likewise marks the project’s folder as trusted in the account’s
config.tomlbefore each turn, since Codex reads the folder’s Protection rules only in a trusted project (Folder trust).
The rule that a session commits and merges its branch into main when the task is done comes with the launch and handoff prompts, plugin or not (in PR mode the prompt says to end the turn for a pull request instead).
A session gets the project’s CLAUDE.md, AGENTS.md and skills as they are committed on the main branch: its worktree is checked out from there, so a file you have not committed yet does not reach it. Which of them each agent reads is in the project’s instructions and skills.
Removing a project
Section titled “Removing a project”A project is removed at the bottom of its Settings → Repository; the page refuses while its chain runs or waits in the queue, a session works for it or in its folders, or a task still holds a place, and says which. Removal does not touch the repository, its worktrees or branches.
Trackers and plugins
Section titled “Trackers and plugins”A project’s tasks come from a tracker. The built-in one needs nothing; any other needs a tracker profile, the account Even Keel signs in with. On top of that, a package gives the sessions tools to read and write tasks themselves.
No account: the built-in tracker
Section titled “No account: the built-in tracker”Even Keel has a tracker of its own, kept in its state database: no account, no token, nothing to connect.
It is the first choice of the tracker in the setup and in Add project, and the one picked when you have no tracker profile; you give the project only its key (APP for APP-12).
Status and Settings → Trackers and CI always show it.
In a built-in project’s Tracker → Configure the Chain rules have only the labels: its statuses are fixed, while its labels are the project’s own and the shared label rules apply to them as to any tracker, so they show there and can be changed for the project. Project tasks and Components follow, and the milestones you name there are created in it on save.
Under Project tasks the Milestone order block lists every milestone of the project, closed ones folded at the bottom. + New milestone and a row’s pencil open its editor: name, status (Planned, Active, Completed, Canceled), target date, description. The status is for you: the chain still follows its milestone rules and the tasks’ statuses, and closing a milestone with open tasks only warns. A rename follows into the project’s chain rules and milestone order. A milestone with done tasks cannot be deleted — cancel it; otherwise deleting it moves its open tasks to another milestone or to none, and drops it from the rules and the order.
Components sort a project’s tasks by area, at most one a task: create, rename and delete them there, and pick a task’s one in its card under Milestone (typing a new name there creates it). The chain ignores them, except for Lanes by component; sessions can set a task’s component by name but never create one. Deleting a component moves its tasks, closed ones too, to another component or to none. The card’s Estimate has a pencil: type minutes or hours (“20”, “1h 20m”, “1.5h”), Enter saves, an empty field clears it.
A project with another tracker’s tasks moves to the built-in one through the import (Moving from a real tracker), not by switching the tracker field.
For sessions to file and edit its tasks themselves — record decisions, split a task, link a blocker — a project needs the package tasks@even-keel.
A project you add gets it on from the start; one added before it, or one where you turned it off, turns it on in the project’s packages (the project’s settings → Sessions → Project packages, the first button of the tab).
Each session keeps its own task in the prompt and gets five short tools for the others; nothing can be deleted through them.
A session you start by hand reaches the same tools when the tasks plugin is installed in it (claude plugin install tasks@even-keel --scope project), as long as Even Keel is running, since the tools are the service’s own: see plugins/tasks/README.md.
Chain sessions get the new version of tasks@even-keel and Even Keel’s other plugins with each new Even Keel by themselves. Claude Code keeps its own copy of a plugin it installed, so after an Even Keel update run claude plugin update tasks@even-keel --scope project in each repository where you installed it, and the same for its other plugins there.
The same package and plugin work for a project on Huly, GitHub, Linear, Jira, GitLab or Forgejo too, with a few limits of each tracker listed there, and for a project’s task feeds: a session on a feed’s task comments and files its blockers in the feed’s tracker, and a task search covers every tracker of the project.
Attachments and edits
Section titled “Attachments and edits”A screenshot or any file pasted (Ctrl+V) or dropped into a task’s description while you edit it becomes the task’s attachment: a picture shows in the text, every file is listed under Attachments in the card, and the task’s session gets their paths to open.
The files lie next to the state database, in state/even-keel/files, and npm run storage -- backup copies them.
A file over 25 MB is refused; the limit is Attachment size limit, MB in Settings → Interface.
An edit of a task’s title or description in its card is saved when you leave the field, close the card or close the tab; only Escape on the title and Cancel in the description editor drop it.
The browser keeps what you typed until Even Keel takes it, so an edit cut off by a closed tab is sent again the next time you open the card, and a note you have not sent waits in its field.
Change history
Section titled “Change history”The task’s journal also records every change of its fields — status, title, description, priority, milestone, estimate, run, labels, parent, links and subtasks — with who made it: you, an agent with its model, or Even Keel itself (a status the chain moved).
One author’s changes within five minutes make one entry, a table of each field’s old and new value; a description change folds out its difference.
The filter over the journal shows All, only Comments or only Changes. Tasks created before this version have no history of their earlier changes.
A session reads the history only when it asks for it (task_read with history: true), so it costs no context otherwise.
Moving to a real tracker
Section titled “Moving to a real tracker”To take a built-in project to a real tracker, open its Settings → Tracker and press Move to another tracker.
Pick the tracker profile and the project in it (and a key where the tracker needs one); the window then counts what will move (tasks, comments, attachments, links, milestones, labels), shows which status each of your statuses becomes there, and lists what will not move — labels and milestones the tracker lacks (create them there and press Check again), priority or estimates it cannot hold, links to closed tasks.
Move copies the open tasks with their statuses, parents, links, attachments and journal; closed ones stay in Even Keel.
Turn on Move the closed tasks too to take every task, done and canceled ones as well, so the decisions and links behind finished work move with it. Trackers do not accept back-dated tasks: a closed task is created and closed on the day of the copy, and its journal starts with the dates it was created and closed in Even Keel. Everyone subscribed to the project gets a notification for each such task, and on GitHub its limits on creating issues stretch a long move over hours. Like the history switch, the choice holds for the whole copy, and Switch then waits for the closed tasks too.
The change history does not become the tracker’s own: no tracker accepts past changes through its API. Turn on Change history as one comment and each task gets one more comment, a table of when, who, which field and its old and new value; the choice holds for the whole copy.
Every comment the copy writes, the summary too, comes from the profile’s account and starts with who wrote it and when. A personal token always writes as its owner, so for the copy to write as a bot, add a profile on the bot’s own token: a GitHub App, a Linear OAuth application, a GitLab project access token, a separate Huly or Forgejo account; in Jira a separate user takes a paid seat.
The copy runs in the service: close the window or the tab and come back to it. When the tracker says it takes no more writes for now (its rate limit), the copy waits the time the tracker names, or a pause that grows while it keeps refusing, and goes on by itself from the same place; the window says until when it waits. To GitHub it writes no faster than 60 a minute, under GitHub’s limits, so a large project takes a while but is not refused. A restart of the service breaks the copy off, and it goes on by itself once the service is back. If a write is refused for another reason, the copy stops and Continue goes on from where it stopped.
While it runs, the project’s tasks cannot be edited.
When the copy ends, Even Keel counts both sides again — tasks, comments, attachments, links, milestones and labels, only what the tracker keeps — and shows them side by side; a row that did not match is red and names the tasks short of it. Repeat brings over what is missing (a task deleted there is created again); Switch without them switches as it is.
Once every task is copied, Switch to
The switch waits until the chain no longer works on the project: stop or pause it, and let a task it holds finish.
The switch keeps a report of the transfer: the plan with what did not move, the count of both sides and what was switched without. It stays as long as the project, under Transfers on the project’s Tracker tab, and the event log’s line of the switch opens it.
Moving from a real tracker
Section titled “Moving from a real tracker”To bring a project’s tasks into the built-in tracker, open its Settings → Tracker and press Move to the built-in tracker. For now Huly, GitHub and Linear give their whole history (GitHub’s issues, not its pull requests; Linear’s archived issues too, not those in its trash); for the other trackers the button is dimmed and its tip says the import comes in a later release.
The window reads the whole project, closed tasks too, and counts what will move — tasks, comments, attachments, links, milestones, labels, components and changes — shows which status each of the tracker’s statuses becomes, and lists what stays behind: links and parents in other projects, time reports, the change history where the tracker gives none, and the milestone fields it does not keep. Milestones move with their target date, status and description, those without tasks too; Linear’s have no status and arrive planned, and a closed one without a closing time (Huly’s) takes the time its last task closed.
Under Authors each author of the tracker’s tasks, comments and changes gets what it becomes here: the agent, you, or a person under their own name. Tasks counts the tasks the author created; their creation is not among the Changes, which count the change log as the plan’s Changes do. Each starts as the tracker marks it; once the copy begins the choice stays.
Move copies every task under its own number, with its status, parent, links, attachments, comments with their authors and dates, and the change log. Nothing changes in the tracker, and the chain keeps working with it while the copy runs.
The copy runs in the service, as the move the other way: close the window and come back; Continue goes on after a stop. When it ends, both sides are counted and shown side by side; Repeat brings over what is missing, Switch without them switches as it is.
Switch to the built-in tracker moves the project once the chain no longer works on it, and keeps the transfer’s report under Transfers. Before the move it brings over the new tasks and those changed in the tracker since the copy (from Linear, every task) and counts both sides again; the window shows each step with its count, and you may close it meanwhile.
Minimum: the adapter only
Section titled “Minimum: the adapter only”Even Keel reads the tasks itself, puts the title and description of the task into the session’s prompt, and closes the task when its branch lands in main.
You add a tracker profile on /settings → Trackers and CI → Add profile, and nothing else: pick the tracker, fill in its fields, and press Check and save.
Even Keel checks the account and saves it if the check succeeds; an error leaves the dialog open without saving.
Check alone shows whom the profile signs in as without saving.
A duplicate-account warning stops automatic saving; press Check and save again to accept it.
The page never shows a saved token or password again. Profiles live in Even Keel’s state database on your machine, not in git.
What each tracker’s profile asks for:
The server address, the workspace, and the e-mail and password of a separate Huly account with access to the projects — create one for Even Keel.
A token instead only if your Huly shows an API tokens page in the account settings: released self-hosted Huly has none, and its sign-in token comes from the e-mail and password anyway (plugins/huly/README.md).
The project key is the Huly project identifier (ABC for ABC-12).
Installed with npm, Even Keel does not carry Huly’s client (about 20 MB): it installs it with npm into state/huly-client of the data folder once you have a Huly profile, which takes a minute or two the first time.
Until then the profile’s check says the client is being installed — press it again a little later — and /status shows the install, with Retry if npm failed; Huly projects wait for it. A clone has the client already.
GitHub
Section titled “GitHub”A fine-grained token on the repositories, with the rights in Token permissions.
A fine-grained token covers one owner: a personal repository and an organization’s need a profile each. The profile shows when its token expires.
A project names its repository: { "repo": "…", "tracker": "github", "github": "octo-org/abc" }.
GitHub has no backlog, so keep entry to the chain on a label: "chain": { "requiredLabels": ["ready"] }.
In a public repository anyone with a GitHub account can open an issue, and a session gives its text to an agent that runs commands on your machine.
So an issue opened by someone who is not the repository’s owner, a member of its organization or a collaborator never enters the chain by itself: without required labels it waits in the backlog until you press Into the chain on it, which puts the label even-keel: approved on it (only people with triage rights can label an issue); with required labels it needs one of them, like any other issue.
Until it has that label, a session’s tasks@even-keel tools do not show it either: the task list only counts such issues, and reading one gives no title, description or files.
The issues of the repository’s own people enter at once unless you set required labels: the wizard says so for a public repository, and the project page keeps saying it in a band, with Rules next to it, for as long as the repository is public and has no required labels — also when it was made public after the project was added.
For the same reason Even Keel reads only the comments of the repository’s owner, the members of its organization, its collaborators and the token’s own account — as an answer to a question, and in PR mode as a review or a comment on a pull request.
Anyone else’s is skipped with a line in the service log; the task card on the page still shows it.
Details and the mapping of statuses, blockers, sub-issues and priorities: plugins/github/README.md.
Linear
Section titled “Linear”A personal API key (Token permissions).
The project key is the team key (ENG for ENG-12); "linear": "Web app" narrows the team down to one Linear project: { "repo": "…", "tracker": "linear", "linear": "Web app" }, so two repositories of one team run as two projects, each on its Linear project.
Details and the mapping: plugins/linear/README.md.
GitLab
Section titled “GitLab”A personal access token with the api scope, and optionally your server’s web address (default https://gitlab.com, without /api/v4; a server under a path prefix keeps it, such as https://example.com/gitlab).
Use GitLab.com or a self-managed GitLab 19.5 or later: those are the versions Even Keel was checked on, and older ones may build parent and child issues differently, so the chain may miss a subtask or close a parent too early.
The profile checks the account and shows the token expiry when the server exposes it.
Pick the project including subgroups: { "key": "APP", "repo": "…", "tracker": "gitlab", "gitlab": "group/subgroup/project" }; issue iid 12 becomes APP-12.
Opened issues are ready, closed ones done; use Required labels to keep unread issues out, especially in public projects.
An issue opened by someone without Reporter access waits for Into the chain even without them, as on GitHub.
Only members with Reporter access or above and the token owner can answer sessions through comments.
GitLab Free has only related links, so no blocking order: the chain follows milestones and priority; Premium or Ultimate adds native blocking links. Text such as blocked by #12 is ignored.
Details: plugins/gitlab/README.md.
Jira Cloud
Section titled “Jira Cloud”The site address (https://<site>.atlassian.net), the e-mail of an Atlassian account that sees the projects and its API token, classic or with scopes (Token permissions).
The project key is the Jira project key (ABC for ABC-12): { "key": "ABC", "repo": "…", "tracker": "jira" }.
Statuses of the To Do category are ready and enter the chain, except one named Backlog; a board whose backlog is not a status needs Required labels or the project’s own active statuses.
The chain is ordered by the Blocks link type: if your site renamed or deleted it, the profile’s projects do not start until a link type of that name is back.
Details: plugins/jira/README.md; the live checks are in verified.md.
Forgejo, Gitea and Codeberg
Section titled “Forgejo, Gitea and Codeberg”The server’s web address (with its path prefix if it has one) and an access token with the rights in Token permissions.
The same profile serves the repository’s issues, its Forgejo Actions and PR mode.
A project names its repository: { "key": "APP", "repo": "…", "tracker": "forgejo", "forgejo": "owner/name" }; issue 12 becomes APP-12.
Open issues are ready, closed ones done; Forgejo has no backlog, so keep entry on a label with Required labels, and in a public repository an issue opened by anyone but the owner, a collaborator or the token’s account waits for Into the chain even without one, as on GitHub; the wizard says so.
The chain is ordered by the issues’ native dependencies (“depends on”).
A repository with dependencies turned off has no blocking order: the chain then follows milestones and priority only, and text such as blocked by #12 is ignored.
Priority comes from labels priority: high, priority/high or priority::high; there are no subtasks and no estimates.
Only comments of the repository’s owner, its collaborators and the token’s own account answer a session; anyone else’s is skipped with a line in the service log.
Details: plugins/forgejo/README.md.
What the adapter alone does not give
Section titled “What the adapter alone does not give”On this level the session does not write to the tracker. What you do not get:
- Postponing on a blocker. The session cannot file a blocker for its task, so it cannot hand the task back and let the blocker run first. Blockers you link yourself still order the chain.
- Question tasks. A session cannot file a
Question: …task for a decision it took on its own; it can only tell you in its final message. - Comments and decisions. Nothing is written back: no closing comment, no decisions folded into the description, no new tasks for bugs found on the way.
- Attachments and discussion. The session sees only the title and the description.
A tracker that does not answer
Section titled “A tracker that does not answer”After a tracker read times out, Even Keel retries that read with an increasing delay, from 20 seconds to five minutes.
Saving a changed profile clears the delay. Repeated timeouts produce one diagnostic line and a recovery line with their count in the service log.
A profile whose server is down for a while — a test server you stopped, say — can be turned off with the switch at the end of its row.
Even Keel then does not contact that server at all: its projects’ tasks are not read, its CI is not watched, and the projects stay on the home page dimmed with Turn on.
A profile with a chain running, paused or queued on it cannot be turned off until you stop the chain.
Turning it on starts nothing: the chain’s Start comes back once the tasks have been read again, so the chain never goes by a list from before.
Sessions you start by hand keep the default profile’s values either way.
The same rule holds after any tracker outage: until its tasks are read again, Start reads them first.
With the plugin
Section titled “With the plugin”On top of the adapter, a Claude Code plugin from this repository gives the sessions the tracker’s MCP server and a skill for working a task: the session reads the task and its attachments, records decisions in the description, files blockers and question tasks, creates new tasks, leaves a closing comment and merges.
There are two kinds of tracker package, and a project needs one of them:
tasks@even-keel, the default. A new project gets it on as soon as it is added, installed in the background if the catalog lacks it; it is an ordinary package, which you turn off or remove like any other. Even Keel’s own tasks server: five tools with short answers, statuses, labels and milestones by name, description patches instead of resending it, no deletes; the same on every tracker. Its tools are the service’s own, so a session you start by hand with thetasksplugin needs Even Keel running — when it is not, the session says so when it starts, and/mcpreconnects the server once the service is up.- The tracker’s own plugin (
huly@even-keel,github@even-keel,linear@even-keel,gitlab@even-keel,jira@even-keel,forgejo@even-keel). The tracker’s own MCP server with its skills: more tools and more context, and it works without the service. Take it instead oftaskswhen you want that tracker’s full set or a particular server.
Wherever the page offers a tracker package, tasks comes first and the tracker’s own plugin beside it. Turning both on in one project works but is not worth it: two tool sets of one tracker double the context and the agent writes through one or the other, so the project’s packages warn about it, with Turn off tasks beside the warning.
Even Keel offers its own plugins from this folder, with no marketplace to add first:
- In Settings → Packages (the package catalog), press Add a package, choose Plugin and pick
tasks@even-keelor the tracker’s own plugin for every project or one. Even Keel copies the plugin, installs a pinned version of its MCP server and gives both to every chain session at launch. A project turns a package on or off in its own packages: the project’s settings → Sessions → Project packages at the top of the tab, where each package has a switch and ↺ puts back the catalog’s default. A plugin your projects already had enabled when you upgraded is in the catalog already. A shortcut for one project: Project packages beside Task description in the prompt in the project’s settings, or the What sessions get chip in the project’s head while its tip says a tracker package is missing, opens the project’s packages with the add dialog over them,tasks@even-keeland the project already picked; while the project lacks a tracker package, its packages show a button for each kind. - The MCP server takes the credentials of the project’s tracker profile: it runs behind a local gateway on
127.0.0.1:4748(EVEN_KEEL_MCP_PORT), so the sessions never see them. Another key a package needs shows in the package’s details in the catalog; until it is set the project’s chain pauses with that reason and Open the project’s packages beside it, and goes on by itself once the key is there. - Nothing to switch off: once a package of the project brings the tracker’s MCP server, the prompt carries only the task ID and the session reads the task itself (
briefleft as auto). The packagetasks@even-keelcounts as that server too: a project with it on and the tracker’s plugin off also gets only the task ID.brief: trueorfalseoverrides that; withfalsethe chain waits while no package of the project brings the server.
With the tasks@even-keel package, task_read downloads files from Huly, Jira, GitLab, Forgejo and Linear tasks and their comments into .temp/task-files/<KEY>/ and returns their local paths.
Linear also collects uploaded files linked in the description and comments; external attachment links stay links.
Files over Attachment size limit, MB are listed as too large, and failed downloads as file unavailable; the task text remains readable.
Linear does not provide a file size on the card, so repeated reads download its files again.
Two different files of one name get separate path prefixes. Adapter details.
The GitLab and Forgejo plugins
Section titled “The GitLab and Forgejo plugins”The GitLab plugin enables the issues,milestones toolsets: sessions read issues through REST get_issue on GitLab.com and self-managed servers, including CE/Free. Work-item tools are disabled because the pinned MCP version’s GraphQL queries fail on CE/Free; native parent-child changes need a compatible work-item tool.
The Forgejo plugin brings the official Gitea MCP server, a single program rather than an npm package: Even Keel does not install it.
Download gitea-mcp for your system from its releases and put it on the PATH of the account the service runs as; without it the plugin’s MCP server cannot start.
Jira: MCP through OAuth or a token
Section titled “Jira: MCP through OAuth or a token”GitHub, Linear, GitLab and Forgejo profiles have nothing to set for MCP: their MCP for sessions box says the sessions use the token entered above.
In a Jira profile’s box, choose OAuth or Jira’s separate MCP token: one is enough, and the token is unused while OAuth is connected.
The profile list shows MCP: connected through OAuth or MCP: reconnect needed.
Check verifies both REST and the selected MCP OAuth access, refreshing it if necessary; Jira also checks that MCP can reach the profile’s site.
Even Keel renews access automatically, so no short-lived token expiry is shown.
After browser consent, press Check and save: an unsaved grant is lost when the dialog closes and expires ten minutes after consent was started. The dialog asks before closing with an unsaved grant.
The Jira profile has Connect MCP through OAuth in its dialog, on a new profile too: a window asks Atlassian for consent, and Even Keel keeps the access and refreshes it; sessions still see only the gateway’s address.
It connects to Rovo MCP v2 and requests the permissions its server advertises; an older Jira MCP OAuth connection needs connecting again in the profile dialog.
GitHub, Linear and GitLab have no OAuth connection: their MCP servers take the profile’s token, and an OAuth connection saved by an earlier version is dropped.
Jira uses Atlassian’s OAuth domain rules: localhost is supported by default.
A custom HTTPS callback needs a matching allowed-domain rule. Without one, v2’s consent page says Access to this domain is restricted and disables Accept, even though client registration succeeds.
Your Atlassian organization’s admin adds the callback domain of your Even Keel page to the allowed domains, not the authorization server’s auth.atlassian.com address; the rule must match the callback URL shown in the dialog.
In the current Atlassian Administration this is Connectors → Atlassian MCP server → Add domain; older screens call it Rovo → Rovo MCP server → Domain settings (Atlassian’s instructions).
Then retry Connect MCP through OAuth.
Open the page over HTTPS, directly or through a local proxy such as Tailscale Service, or on localhost of the machine Even Keel runs on: a plain HTTP address of another machine is refused as a callback.
With direct network access, sign in to the page before connecting OAuth and allow its cookies.
The callback returns to the tracker settings without authorization parameters in the address, including when access is refused.
When access cannot be renewed, the profile’s row says MCP: reconnect needed; open the profile and press Connect again.
Atlassian grants access to whoever is signed in to Atlassian in that browser: if it is another person than the profile’s API token, the dialog and the profile’s row warn that sessions will write as that person.
Saving is still allowed; if it was not on purpose, sign in to Atlassian with the right account and press Connect again.
The MCP token below remains the other way, for a machine without a browser.
If MCP OAuth fails to connect or renew, the service log names the tracker kind, the failed step and the provider’s HTTP error or exception message.
The page shows the connection error; diagnostic details stay in the log, with credentials and callback values redacted. See As a service for the log location.
The Jira plugin is Atlassian’s own Rovo MCP server and needs a separate token from the REST adapter (or the OAuth connection above).
First ask your Atlassian organization’s admin to enable API token authentication for the Atlassian MCP server in the organization’s settings (Connectors → Atlassian MCP server → Authentication).
Then create an Atlassian MCP V2 token with all scopes for the same e-mail and enter it in Atlassian MCP V2 token (optional) in the Jira profile.
Leave it empty for projects without jira@even-keel.
The profile check calls getAccessibleAtlassianResources and requires that it include the profile’s site; if the list is empty or lacks the site, create the MCP token again after enabling API token authentication.
A successful tool listing alone does not prove access.
Details: plugins/jira/README.md.
Sessions you start by hand
Section titled “Sessions you start by hand”Sessions you start by hand get none of this.
For them, Claude Code needs this repository as a marketplace: Accounts offers + Even Keel marketplace in the Claude Code card while your default config (no CLAUDE_CONFIG_DIR set) does not know it; a check mark replaces the button once added.
The card appears after adding a Claude Code account.
Its tip has both commands to copy, or run claude plugin marketplace add <git URL or local path of this repository> yourself.
Then claude plugin install huly@even-keel --scope project in the project and the credentials in the env of ~/.claude/settings.json (HULY_URL, HULY_WORKSPACE, HULY_TOKEN or HULY_EMAIL and HULY_PASSWORD; GITHUB_PERSONAL_ACCESS_TOKEN; LINEAR_API_KEY; GITLAB_PERSONAL_ACCESS_TOKEN and optional GITLAB_URL; JIRA_BASIC_AUTH, the base64 of e-mail:MCP-token, using the separate Atlassian MCP V2 token).
Even Keel writes each tracker’s default profile there itself; the GitHub, Linear, GitLab and Jira MCP variables above use different names, so supply those explicitly for sessions started by hand.
Such a session never gets another profile.
The GitHub skill sets “blocked by” links through the GitHub CLI, so gh auth login once. Everything else — troubleshooting, what the skills do — is in plugins/huly/README.md, plugins/github/README.md, plugins/linear/README.md, plugins/gitlab/README.md and plugins/jira/README.md.
Several trackers
Section titled “Several trackers”Each project has its own tracker (tracker in the project’s entry, GitHub when a file you write names none), and they work at the same time: project A on Huly, project B on GitHub.
A tracker can have several profiles — two Huly workspaces, a personal GitHub token and an organization’s — and each project picks one (the Profile field when you add it, or in its settings until its first task runs).
One profile of each tracker is the default: projects without a choice run on it, it is the one sessions started by hand get, and it gives the GitHub Actions token to projects of other trackers.
Making another profile the default does not move a project whose tasks have already run: it stays on the old profile, now as its own choice.
A profile whose token is refused turns red on Trackers and CI, and the chains on it pause until it is fixed.
Git is not part of this: pushes go through your own git and its credentials (SSH, the credential manager), whatever the profiles are. A project on Huly with a remote on GitHub works as is, and its CI is found by the remote.
A project can take tasks from a second tracker too: in the project’s settings, Tracker → Task feeds → Add a feed, pick the profile (it names the tracker), the place (a repository, a team — the profile’s projects are suggested as you type, as in the wizard) and a key for the ids (Several trackers for one project).
The chain rules a feed’s tasks go by are the project’s own, then its profile’s, then the shared ones: a GitHub feed on a public repository needs its label as much as a GitHub project does, so set requiredLabels on that GitHub profile (its tab under Chain rules, or Rules on its row in Trackers and CI) when the project’s own rules do not set it.
The wizard’s warning does not cover feeds, but the project page’s band does: it names each public source that takes tasks without a label, the feeds included, and the feed’s window says it too.
CI and pull requests
Section titled “CI and pull requests”The CI is read with a profile too.
GitLab CI is found from a root .gitlab-ci.yml file on gitlab.com or a host named by a GitLab profile’s address.
Nested groups are supported. When several GitLab installations share a host, HTTP(S) remotes use the longest matching URL prefix from the profiles, falling back to a root profile.
The token comes from the project’s GitLab profile for that installation, otherwise its default profile, otherwise its first profile. A profile for another installation on the same host is excluded, even when explicitly chosen.
SSH remotes have no installation prefix in their path: the first installation on the host is used, with a log entry when the choice is ambiguous.
GitHub Actions on a github.com remote takes the token of the project’s GitHub profile, or of the default GitHub profile for a project on another tracker.
CI on a Forgejo remote takes a Forgejo profile (Add profile → Forgejo: the server’s address and an access token) on the remote’s host.
Pull requests of PR mode take the same token as the remote’s CI. What each token needs is in Token permissions.
With several GitHub, Forgejo or GitLab profiles, a project can pick the one its CI and pull requests take in Settings → Check and CI (remoteProfiles); “Automatic” is the choice above.
A CI that no profile reaches is not shown at all. CI supports GitHub, Forgejo (or Gitea) and GitLab. PR mode supports GitHub, Forgejo and GitLab (merge requests, on the same profile as the remote’s GitLab CI). A remote on bitbucket.org has no CI and cannot use PR mode.
An unknown host is taken for Forgejo until a GitLab profile identifies it; a Forgejo profile’s check on GitLab asks you to add a GitLab profile instead.
A FORGEJO_TOKEN left in .env from an older install becomes a Forgejo profile on the first start, one per host — that of FORGEJO_URL if .env has it, and those of the projects’ Forgejo remotes; after that it is not read.
A Forgejo profile is a tracker profile too: the same token serves the issues once it has write:issue.
Token permissions
Section titled “Token permissions”What a profile’s token needs, by what it is used for. The profile dialog lists the same for the kind you pick.
| Profile | Tracker | CI | Pull requests (PR mode) |
|---|---|---|---|
| Huly | a separate account with access to the projects: its e-mail and password, or a token | — | — |
| GitHub, a fine-grained token for the repositories’ owner | Issues: Read and write | Actions: Read | Pull requests: Read and write, Contents: Read, Actions: Read |
| Linear, a personal API key | write access | — | — |
| GitLab, a personal access token | api scope (read_api cannot close issues or post comments) |
api scope, with access to the project and its pipelines |
api scope, Developer access or above in the project (pushing the branch, opening a merge request, reading its discussions and the members) |
| Jira Cloud, an Atlassian API token | Browse projects, Add comments, Transition issues and Edit issues in the projects; a token with scopes also needs read:jira-work, write:jira-work and read:jira-user |
— | — |
| Jira plugin, a separate Atlassian MCP V2 token | All scopes of the Atlassian MCP V2 application; enable API token authentication for the Atlassian MCP server before creating it. The REST token cannot be reused | — | — |
| Forgejo, an access token | write:issue (reading issues and their dependencies, comments, closing, labels and milestones), read:repository (the repository list and the collaborators), read:user (the sign-in check); for an organization’s repository also read:organization (the organization’s labels), without which the project page says that its labels and milestones are not read |
read:repository (the repositories and their Actions), read:user (the sign-in check) |
write:repository (opening a pull request, reading its reviews and its reviewers’ access), read:issue (comments in its conversation), read:user; for reviewers other than the account and the repository’s owner the account must be an admin of the repository |
PR mode pushes the task’s branch with git push, on the git credentials of the account the service runs as (its SSH keys or credential manager), not with a profile’s token: without them PR mode stops at the push.
A forge that refuses to open a pull request with the token marks the profile’s row PR refused and names the right it lacks.
If the chain pauses because a pull request could not be opened, fix the token or select a profile with access in the project’s Check and CI settings, then press Resume.
Even Keel retries the same pull request mark without sending anything to the task’s session; another failure pauses the chain with its new cause. Changing the profile alone does not retry it.
A push refused because the branch on the forge has commits the task’s session lacks — you resolved a conflict on the forge, say — does not pause the chain: the session is told to merge the branch from the forge and mark the pull request again.
Even Keel never force-pushes, so your commits on the forge stay.
The Forgejo rights for pull requests follow from the API calls Even Keel makes and are not yet checked against a real server (What has not been verified).
The page
Section titled “The page”http://localhost:4747 by default. The page can be installed as an app (the install button in the address bar of Chrome or Edge) and then opens in its own window; browsers offer this on localhost or over HTTPS only.
Answering from the phone
Section titled “Answering from the phone”Sessions can be answered from the page’s chat or the tracker.
To answer them in Claude’s own app as well, use Remote Control: a Claude account added from the page with a claude.ai sign-in has it on, and the page links each session’s Remote Control. For an account where it is off, “Turn on Remote Control” in the account row’s menu or the session panel turns it on from the account’s next session. This also resolves a pending edit to that setting.
Codex sessions have no remote control: they run through codex exec, whose threads the Codex app and ChatGPT on the phone do not list, so they are answered only from the page’s chat or the tracker (docs/sessions/codex.md).
Reaching the page from another machine
Section titled “Reaching the page from another machine”By default the page listens on 127.0.0.1 only, and nothing else on the network sees it. That is on purpose: the page starts sessions with automatic permissions, writes answers into waiting sessions and signs Claude accounts in and out, so whoever reaches it drives your machine. Every request is also checked whatever EVEN_KEEL_HOST is:
- its
Hostmust belocalhost,127.0.0.1,[::1],EVEN_KEEL_HOSTor a name inallowedHosts, otherwise it gets 403. This stops DNS rebinding — a foreign site whose name was pointed at127.0.0.1; - an
Origin, if the request has one, must be the page’s own: the same name and port as itsHost(https://namematches aHostofnamewithout a port, as an HTTPS proxy sends it). So neither another site open in your browser nor another app on the same name — a dev server onlocalhost:5173, a service on another port of your tailnet name — can post to the page. Requests withoutOrigin(the plugins’ hooks,curl) pass; - a
POSTto/api/must beContent-Type: application/json, otherwise it gets 415: a browser cannot send that type to another site without asking it first. A script posting to the API sends the header, ascurl -H 'Content-Type: application/json'does.
Open Even Keel directly in a tab or its installed app: the page and the access-token form cannot be embedded in a frame, even on the same site.
Its content security policy permits scripts and connections only from its own origin, with inline styles and local/data/blob images and media. The page sends no referrer.
If using a reverse proxy, preserve these response headers. An already open tab receives a new policy when reloaded.
Two ways to reach it from elsewhere:
- A proxy on the same machine (recommended). For example a Tailscale Service,
tailscale serve --service=svc:even-keel --https=443 http://localhost:4747, which also gives the page HTTPS, so it can be installed as an app. The proxy forwards the name it was reached by, so put that name intoallowedHosts:"allowedHosts": ["even-keel.example.ts.net"]. Its requests come from loopback, so the page asks them for no token: who gets in is decided by the tailnet’s access rules. - Listening on the network. Set
EVEN_KEEL_HOSTin.envto0.0.0.0or the machine’s address, put the names or addresses you open it by intoallowedHosts(the configured address itself is let in), and setEVEN_KEEL_TOKENin.env. Without the token the service does not start. A request from another machine then needs the token: open the page once ashttp://<address>:4747/?token=<token>, and the service keeps it in anHttpOnly,SameSite=Strictcookie and drops it from the address; scripts sendAuthorization: Bearer <token>. Plain HTTP shows the token to anyone on the way, so prefer a proxy with HTTPS.
Any proxy or tunnel running on the same machine must control who can reach Even Keel.
The page does not ask for a token on connections from this machine, through loopback or its own address, even when EVEN_KEEL_TOKEN is set.
Once the forwarded name is accepted by the Host check, a public tunnel without its own authentication lets anyone who knows its address drive the page and start sessions with automatic permissions.
allowedHosts permits a name; it does not authenticate visitors. HTTPS encrypts the connection but does not decide who may enter.
The page and the MCP gateway trust every OS user account on this machine, not just the account running Even Keel.
Another local user can call the page at 127.0.0.1:4747 or the gateway at 127.0.0.1:4748 (the default ports) without a token, including the tasks server’s tools for any project, and can run code as the service account.
Install Even Keel on a machine with no other users, or trust every user as much as the service account.
Starting MCP OAuth also sets a separate ten-minute HttpOnly, SameSite=Lax cookie for the callback alone, so the browser can return from the provider. The page’s access cookie stays SameSite=Strict; the callback cookie cannot open other pages or API routes.
As a service
Section titled “As a service”The service starts by itself and restarts Even Keel if it fails. Stopping the service does not kill running sessions: they belong to the CLI’s daemon.
| Runs as | Log | |
|---|---|---|
| Windows | a start at your sign-in, with a tray icon (below) | logs\even-keel.log |
| Linux | a systemd user unit | journalctl --user -u even-keel |
| macOS | a launchd agent local.even-keel |
logs/even-keel.log |
The log folder is the data folder’s when installed with npm, the clone’s own otherwise.
Installed with npm
Section titled “Installed with npm”npx even-keel installs the package globally (npm install --global even-keel) and sets the service up: on Windows the start at sign-in below, elsewhere the package’s own install script. Once installed, these set it up again and remove it:
even-keel installeven-keel uninstalleven-keel with no command runs Even Keel in the terminal, on the same data folder.
Once the service is set up, even-keel install and even-keel update wait up to 30 seconds for the page and print Open <address>, the address built from EVEN_KEEL_HOST and EVEN_KEEL_PORT (the environment, then .env of the data folder); a page that does not answer by then gets its address and the log’s place. Only the first install from npx opens the address in your browser, and only when the page answered: never over SSH, and on Linux only with a display (DISPLAY or WAYLAND_DISPLAY) and xdg-open. On Linux without systemd there is no service, so it prints where the page will be once you run even-keel.
npm’s global folder on macOS and Linux
Section titled “npm’s global folder on macOS and Linux”Node from the nodejs.org installer puts npm’s global folder under /usr/local, which belongs to root, so npm install --global fails with EACCES. npx even-keel checks the folder first and, when it cannot write there, installs nothing and prints these commands: they move the folder into your home (~/.bashrc instead of ~/.zshrc in bash; with SHELL empty, as under docker exec, the shell of your account in /etc/passwd, and ~/.profile when that is unknown too).
mkdir -p ~/.npm-globalnpm config set prefix ~/.npm-globalecho 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrcsource ~/.zshrcnpx even-keelDo not use sudo instead: sudo npx even-keel would install the service for root, with root’s data folder and accounts, and after a sudo npm install --global an update from the page fails the same way. npx even-keel refuses to run as root. Node from nvm or Homebrew leaves the folder writable by you and needs none of this.
The service runs from the global install, never from npx’s cache, which npm may clear. The package keeps nothing of yours in its folder, since npm replaces the folder at every update: .env, state/ and logs/ are in the data folder.
| Data folder | |
|---|---|
| Windows | %LOCALAPPDATA%\even-keel |
| macOS | ~/Library/Application Support/even-keel |
| Linux | $XDG_DATA_HOME/even-keel (~/.local/share/even-keel) |
EVEN_KEEL_DATA names another folder. The install script builds nothing; on Windows it puts the service host into the data folder too. The service must run as the user whose data folder it is; for another account, pass -Data <folder> to install.ps1 (or set EVEN_KEEL_DATA).
A clone as a service
Section titled “A clone as a service”After npm run build, as your own user. On Windows:
node dist/src/cli.js installOn Linux and macOS:
service/install.shFrom a clone the install also installs the dependencies and builds the page.
Windows: a start at sign-in
Section titled “Windows: a start at sign-in”even-keel install (a clone: node dist/src/cli.js install) runs as your own user, with no administrator and no PowerShell 7. It:
- installs the dependencies and builds the page (a clone only);
- compiles a small host
EvenKeel.exewith thecsc.exethat ships with Windows (.NET Framework 4), into the data folder’sservice(a clone:service\bin); - adds it to your sign-in start (
HKCU\Software\Microsoft\Windows\CurrentVersion\Run, the valueEvenKeel), which shows in Settings → Apps → Startup and can be turned off there; - starts it.
The host keeps Even Keel running, restarts it if it fails and puts an icon in the tray:
- Open the page, or a double click on the icon;
- Restart, which also picks up programs installed since, git or an agent CLI: Even Keel starts with the system and user
PATHread anew; - Quit, until your next sign-in;
even-keel installstarts it again.
The dot on the icon and its tooltip say how it is:
| Dot | Means |
|---|---|
| green | it runs |
| amber | a chain is paused |
| blue | a session waits for your answer |
| grey | starting, or stopped for an update |
| red | it does not answer |
It runs only while you are signed in. After a Windows Update restart at night Even Keel waits for you to sign in, unless Windows signs you back in to finish the update: Settings → Accounts → Sign-in options → “Use my sign-in info to automatically finish setting up after an update” (an organization’s policy may turn that off). Signing out stops it; running sessions go on as they would after any stop.
Windows: PowerShell
Section titled “Windows: PowerShell”Run the commands from cmd, or add .cmd to them in Windows PowerShell and PowerShell 7:
npx.cmd even-keeleven-keel.cmd installnpm puts a .ps1 wrapper next to each .cmd one, PowerShell picks the .ps1, and its default execution policy refuses to run it (“running scripts is disabled on this system”). Even Keel does not change the policy for you; if you want plain npx and even-keel there, this lifts the block:
Set-ExecutionPolicy -Scope CurrentUser RemoteSignedThe commands Even Keel itself suggests are written for cmd.
Windows: without a sign-in
Section titled “Windows: without a sign-in”For a machine where Even Keel must run with nobody signed in, a clone can still be the Windows service EvenKeel. From PowerShell 7 as administrator:
service\install.ps1It installs the dependencies, builds the page, compiles the service host the same way and registers the service under your account. The script never asks for your password: enter it in services.msc → EvenKeel → Properties → Log On, which also grants the “Log on as a service” right, then start the service.
One of the two per machine: they would take the same port, so even-keel install refuses while the service is installed, and install.ps1 refuses while the start at sign-in is.
Windows: long paths
Section titled “Windows: long paths”Even Keel’s own git calls handle paths past 260 characters already, and cleanup deletes a worktree folder git could not. For your own git and the sessions’ git (deep node_modules in a worktree), turn long paths on once:
git config --global core.longpaths trueAnd the registry value LongPathsEnabled, from PowerShell as administrator:
New-ItemProperty -Path HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem -Name LongPathsEnabled -Value 1 -PropertyType DWORD -ForceLinux and macOS
Section titled “Linux and macOS”even-keel install (a clone: service/install.sh), as your own user, not with sudo. The script takes PATH and node from your shell; if node changes (nvm and the like), run it again.
Linux: a systemd user unit; systemctl --user status even-keel shows it. A user unit stops when you log out; to keep it running:
loginctl enable-linger $USERA Linux without systemd (WSL without systemd=true, OpenRC or runit) has no service to install: the script writes no unit, says so and exits with code 3; npx even-keel still leaves the package installed. Run even-keel (a clone: npm start) in a terminal or under your own process manager. On WSL, systemd is turned on by [boot] and systemd=true in /etc/wsl.conf, then wsl --shutdown. The same message comes when systemd runs but the shell has no user session of its own (after su or sudo -u): sign in as that user directly.
macOS: a launchd agent local.even-keel. It runs while you are signed in to the Mac’s desktop, at the screen or through Screen Sharing; signing out stops it. An SSH login alone is not enough: the script then stops and asks you to sign in to the desktop first. A Mac without a screen keeps its desktop session through automatic login (System Settings → Users & Groups; needs FileVault off).
On both systems the installer waits up to 60 seconds for the service and its page to answer before reporting success.
It uses the address in your data folder’s .env; EVEN_KEEL_HOST and EVEN_KEEL_PORT set in the installer’s shell take priority and are saved in the service definition.
A protected page can pass without entering its token.
On failure the installer exits with an error, shows the service state and recent log, and leaves the installation in place. Fix the reported problem and run the installer again.
On macOS also check System Settings → General → Login Items → Allow in the Background: the entry may be called node.
The service log records stop signals and fatal errors; it cannot record a forced kill or a machine failure.
A machine of a hub (preview)
Section titled “A machine of a hub (preview)”The first installation is the hub: it has the page, the trackers and the chains, and runs sessions itself. Another computer can join it as a machine: an installation with no page and no projects of its own that the hub gives projects to. The hub gives the chain’s tasks to the machines of each project’s pool. Preview: joining, the pool and tasks on a machine are built but not yet checked live end to end.
-
On the hub, press + Machine: at the foot of the machines panel, which opens from the machines block in the header, or, while the hub is the only machine and there is no panel yet, in Settings → Interface under Hub address for machines.
-
In the window, pick the Hub address for machines — the name or IP the other computer reaches the hub by: one of the page’s allowed addresses, an address of a network adapter, or one you type — give the machine a name if you like (without one it is named by its host name) and a colour, its mark in the chain and the lists (the next free one is offered). Issue the command remembers the address for the next machines; the hub then listens for machines on port 4749 (
EVEN_KEEL_MACHINES_PORT). The window shows the command with its connection string: good for 30 minutes and one machine; Issue again takes back the one not used yet. -
On the other computer, with Node.js 24 and git installed, run the command the window gave, the same on Windows, Linux and macOS:
Terminal window npx even-keel@<the hub's version> install --machine <connection string>The version is the hub’s. A machine of another version gets no new tasks: it finishes the ones it has, and its page on the hub says which version to install and gives the command to run on the machine,
even-keel update <the hub's version>. Update the hub first, then each machine. A machine the hub refuses outright (the link between them changed) updates itself to the hub’s version if it is a global npm install, or to the hub’s commit if it runs from a git checkout, and comes back; when it cannot — local changes in its checkout, no service, or a failed update, which it does not retry until the hub moves on — its page on the hub says so.--root <folder>names the folder the machine’s projects go into (by defaultprojectsin its data folder); the hub puts each project in a folder of its own there and reaches nothing outside it.
The command installs the package globally, joins the hub and installs the service the same way as for a hub: on Windows the start at sign-in with its tray icon (add --service for the Windows service EvenKeel, from PowerShell 7 as administrator, as in Windows: without a sign-in), on Linux and macOS the user service. It then waits up to 30 seconds for the machine to reach the hub and says whether it did. Without Node.js 24 or git it installs nothing and says what is missing. Run it again (an update, a failed install) with the same string: the machine stays joined and only the service is installed again.
A machine or a hub in Docker. The window’s Docker switch gives the same machine as a container: the line for the Compose folder’s .env, the join and the start. Each of the four ways — hub and machines on hosts, either of them in Docker, both in Docker — and how machines on several hosts are updated are in Installing with Docker, Machines.
A machine from a clone. The window’s command names the hub’s version, and a hub that runs from a clone between releases has the last release’s version, which has no machines yet. Make such a hub’s machine from a clone at the hub’s commit instead, with the connection string:
git clone https://github.com/NamerekT/even-keel.git && cd even-keelgit checkout --detach <the hub's commit>npm ciservice/install.sh --machine '<connection string>' --root ~/projectsThe script builds the machine without the page (npm run build:machine), joins and installs the user service. On Windows, build with npm run build:machine and run node dist/src/cli.js install --machine '<connection string>' for the start at sign-in, or service\install.ps1 -Machine '<connection string>' -Projects <folder> for the Windows service, from PowerShell 7 as administrator. Such a machine follows the hub’s commit by itself.
A machine that goes away — switched off, off the network, or revoked — keeps the tasks it was running: the chain does not hand them to another machine by itself, since the machine may come back with its work. Such a task’s row in the chain shows Reassign once its branch is on the remote: another machine then goes on with it from the pushed branch and the last handoff note, and the machine that left does not take it back. Only the commits of a turn still running when the machine went away are lost: the branch is pushed at the end of every turn.
The window waits for the machine and, when it joins, shows what it found there — Node.js, git with its user name and e-mail, the agents’ CLIs — and what fails without a missing one, then the hub’s projects to connect it to — for each one ticked, its folder there, by default the project’s folder name in the machine’s folder of projects (another folder… takes a full path), with what is there under it: a free folder gets a clone of the project, a folder with its clone is taken as it is, and a folder holding something else says what to do and keeps Connect off. The same folder field is in Connect a machine of a project’s Machines tab. Connect checks each folder in turn in a progress window (a git repository with one of the hub’s remotes, the branch, the right to push), and a failed check says what to fix and offers Retry — and the hub’s accounts to sign in to there, with Sign in on this machine. You can close the window while it waits: when the machine joins, a notice opens the window at its projects. A machine takes no task of an agent it has no account for, nor one whose project’s account is not signed in there: it runs the same account in any folder of its own, a long token of it included, while the hub or another machine of the pool runs the task. When no machine of the pool has that account, the project pauses with “The project’s account … is not signed in on machine …” and Add account with that machine picked.
A new project on several machines. Once the hub has a machine, the wizard’s Repository step lists the machines in place of the field Folder. Tick each machine the project runs on: a ticked row opens its folder there — the machine’s folder of projects and a name, or another folder… with a full path — and says under it whether the folder is free (the project is cloned there), already holds a clone of this repository (it is taken as it is) or holds something else (with what to do). The hub can be unticked too: the project then does not run on it. A new folder or a repository without a remote stays on the hub only, since the other machines take a project only through its remote; a machine off the link is connected later from the project’s settings, Machines. A machine where no agent is signed in is connected all the same, with Sign in on …: tasks do not go there until an agent signs in. Creating the project connects each ticked machine in turn in the progress window; one machine failing leaves the others connected, and the window names it with its fix above Retry.
Commands of its own. A machine may run a project differently: in the project’s settings pick the machine and open its settings tab; The machine’s own commands takes its commands before the start, its check commands, its commands after a green main and, for each stdio server of the project’s packages, another command or arguments — say, another path to a program or a folder. A field left blank is the project’s, shown in it in grey. Connect a machine can copy them from another machine of the project. Connecting refuses a machine where a server’s command is not found. After a green main, every machine of the project with commands after it brings its own clone’s main up to the green commit and runs them there; a machine that was off then runs them once when it is back, for the last green commit only. The tab Machines shows under each machine what it runs.
The tray icon of a machine is green while it hears the hub and red when it has not for three minutes; it has no page to open. even-keel status prints the hub, the folder of projects and the last contact.
Accounts on a machine. A machine runs sessions on its own sign-ins, never the hub’s. Under each subscription account on the hub’s accounts page, a line names every connected machine where that account is not signed in, with Sign in: the sign-in runs on that machine, its link opens in your browser, and the code from the sign-in page goes into the window on the hub’s page, which hands it to the machine. The account stays on the machine: the hub keeps neither its token nor its credentials file. A machine without the agent’s CLI says so instead of offering the button.
Pick a machine in the machines panel and open the accounts page to see that machine alone: its accounts with the limits it read, a signed-out one with Sign in, and below them every hub account not signed in there, each with Sign in too. Add account at the top adds an account to that machine only: choose the agent (one whose CLI the machine lacks is greyed with a tip), then sign in in the same window. Both are greyed while the machine is off the link.
Once the hub has a machine, Add account anywhere starts with Where it signs in: the hub or one machine on the link. Opened from a machine’s page or its accounts, that machine is picked; elsewhere, the hub. On a machine, a Claude account can also come in on a Long token of claude setup-token for a hub Claude subscription not signed in there yet: no browser on the machine, but no Remote Control either.
One machine per folder. A machine, the hub’s own included, marks each project folder it serves with the file .git/even-keel-machine. Another machine or installation that reaches the same repository — over a network share, from a container, from a second installation — is refused it, and its chain pauses with “already served by machine …”. Revoking a machine takes its marks off. When the marking machine is gone for good, press Take the folder over under the chain’s pause: the page names the machine that loses the folder and asks to confirm, then takes the folder and resumes the chain. A machine that is still running stops working in that folder. For a machine elsewhere, open its page from the machines panel: each folder another machine holds there is a band “Another machine holds the project’s folder” with the same Take the folder over and the same confirmation.
Behind a proxy. The link is one long HTTPS stream from the hub, and the connection string carries the fingerprint of the hub’s own self-signed certificate: the machine talks only to a hub that shows exactly that certificate. A router’s port forward or a proxy that passes the connection through as it is (a TCP forward, nginx stream) works as it is. A proxy that ends TLS itself — a reverse proxy, a Cloudflare tunnel — shows the machine its own certificate, and the machine refuses a hub pinned by its fingerprint. For such a hub turn on Behind a proxy with a public certificate under the address in the + Machine window: the string then carries no fingerprint, the machine checks the proxy’s certificate as any HTTPS site’s (it must be of a public authority, such as Let’s Encrypt or Cloudflare’s own), and an address without a port means 443. The window remembers the choice in this browser. The hub still listens for machines over HTTPS with its self-signed certificate, so the proxy forwards to https://<hub>:4749 without checking that certificate: nginx’s proxy_pass https://… does so by default, a Cloudflare tunnel needs noTLSVerify: true for that service, Caddy tls_insecure_skip_verify. An antivirus or a corporate proxy that inspects HTTPS shows a certificate of its own authority, which a string with a fingerprint refuses as it should. A proxy on the way must also not hold the stream back and must keep it open: for nginx proxy_buffering off; proxy_read_timeout 1h;; an idle timeout such as a Cloudflare tunnel’s 100 seconds needs nothing, the hub sends a pulse more often. When a proxy holds the stream, the connection opens and nothing comes over it, and the machine reconnects again and again: its log then says “a proxy on the way seems to hold the stream back”. Turn that proxy’s buffering off for the hub’s address for machines, or take the proxy off the way.
Updating
Section titled “Updating”Docker installations update by pulling the image.
A hub running from a checkout can rebuild after a green push. Use service/rebuild.sh <green-sha> for the systemd user service or macOS launch agent, or service/rebuild.ps1 -Commit <green-sha> on Windows. The checkout must already be at that commit. If the rebuilt service cannot start or answer, Even Keel rebuilds the previous running commit and shows both commits on the page. The next green push can try again. See Rebuild mode for setup and the update log.
The gear menu in the header ends with the installed version.
Even Keel asks GitHub for its latest release at start and every 12 hours (a request to api.github.com without a token; it names only the installed version); a newer one gets a mark next to the version and a notification in the corner of the page.
Turn the check off on /settings → Interface or with "updates": { "check": false } in the config.
From the page
Section titled “From the page”The mark and the notification open the update window: the installed version, the notes of every newer release, and Update to <version>. A release marked as a revert release (its notes have a Reverted section) says what of an earlier release it takes back. The update:
- waits, up to 5 minutes, until no chain is starting a session, handing over or closing a task — a restart in that moment would pause the chain; the page shows which projects it waits for. A chain held by an account or model limit, with no current task or closing, does not delay the update if the reset is more than a minute away, or unknown for a model’s week;
- stops the service, checks out the release’s tag (
git fetch --tags,git checkout), runsnpm ciandnpm run build, and starts the service again; installed with npm, it runsnpm install --global even-keel@<version>into the same global folder instead; - waits up to 2 minutes for the service to answer with the new version and keep running.
If any step fails, including no answer, it checks out the commit it started from, installs and builds it again (with npm: installs the version it started from) and starts the service: you are back on the version you had. Either way the page reloads by itself and says how it went; Details shows the failed step and its output, and the whole log is logs/update.log (the outcome itself is in logs/update.json). Running sessions are not touched.
The button is there only when Even Keel runs as a service and its folder is:
- a global npm install, or
- a clean git checkout on the tag of the installed version; a clone that you update with
git pullon the main branch is one.
Otherwise the window says why and you update by hand. A checkout that was on a branch stays on it (moved to the new tag), so a later git pull still works.
After an update the window and the gear menu also offer Revert to <previous version>, the same process in the other direction, as long as the update did not change the format of the stored state.
When it did, the older version cannot read the state any more: the window says so, and going back is the manual way below, losing what was written since. In that case it is better to wait for a revert release, which keeps the new format.
After a revert the newer release is offered again; nothing updates by itself.
Once the version is changed by hand (below), the window no longer shows how the last update from the page went, nor offers to revert it.
By hand
Section titled “By hand”Running sessions are not stopped by any of this: they belong to the CLI’s daemon, and the restarted Even Keel picks them up.
Installed with npm. This stops the service, installs the latest release into the same global folder and starts the service again:
even-keel updateeven-keel update 0.2.0 installs that version. A release candidate from npx even-keel@next moves to the newer of the latest release and the latest candidate; when nothing is newer, the command says so and leaves the service running. Unlike the button it does not wait for the chains, and a failed install leaves the version you had.
Run from a terminal, not as a service: stop Even Keel, then start it again after
npm install --global even-keel@latestA clone as a service. Pull, then run its install again: it installs the dependencies, builds the page and restarts the service. On Windows:
git pullnode dist/src/cli.js installOn Linux and macOS:
git pullservice/install.shThe Windows service without a sign-in takes service\install.ps1 instead, from PowerShell 7 as administrator.
A clone run from a terminal. Stop Even Keel, then:
git pullnpm cinpm run buildnpm startOn Windows a running Even Keel holds files in node_modules: npm ci next to it fails with EPERM and leaves the folder half-removed. Stop Even Keel and run npm ci again.
Trying the next version
Section titled “Trying the next version”With npm, the latest release candidate, when there is one:
npx even-keel@nextOr switch a clone to the dev branch and build it again (back to the release: the same with git switch main):
git switch devgit pullnpm installnpm run buildnpm startdev is not a release: the page offers no updates on it, and the state it writes may be too new for the release to read, so test it in a separate clone.
Plugins
Section titled “Plugins”The plugins come with the code; agent-bridge is built in and on in every project, so there is nothing to add for it.
Chain sessions run the version of a package installed in Settings → Packages: its row shows the newer version the marketplace has and an Update button, or Check in its details when it knows of none (for a git URL marketplace both run claude plugin marketplace update first). Above the catalog, Check all fetches the plugins’ marketplaces again and only shows the newer versions; Update all then presses every row’s Install and Update in turn, and a package that fails keeps its error in its row while the rest go on. A new npm version of an MCP server is found by its row’s Check.
Even Keel’s own plugins are read from this folder and are a part of its version: after an update, every one of them in the catalog that is not removed gets its new version by itself within a minute, with no Update press, including one turned off in a project. A running task stays on the version it started with until it is done.
For sessions you start by hand, a marketplace added from the local path of this folder offers the new plugins by itself, but Claude Code keeps its own copy of each plugin it installed: run claude plugin update tasks@even-keel --scope project (or huly@…, github@…, linear@…, tally@…) in each project repository that installed it. A marketplace added from a git URL needs claude plugin marketplace update even-keel first.
If you installed the former checkpoint@even-keel plugin in Claude Code, run claude plugin uninstall checkpoint@even-keel in each configuration folder where it was installed. There is no need to install agent-bridge by hand: Even Keel supplies it to chain sessions, and its hooks stay silent in sessions started by hand.
Stored state
Section titled “Stored state”A new version may store the files of state/ in a newer format: at startup, before anything else, Even Keel rewrites them to it and keeps each old file next to it as <file>.v<N>.bak (the log names them).
It rewrites all of them or none; a file it cannot read, or one written by a newer version, leaves the service with only the page, which shows the reason.
The projects, the settings, the chain’s state, the questions posted to the tracker, the launch log and the handoff snapshots live in one database, the folder state/even-keel/ (PGlite, the embedded Postgres the statistics use too).
Next to it Even Keel keeps state/machine/ for the part that runs sessions. It holds account registrations, management keys, account limits and transferred settings, CLI choices, and pending messages to the hub. Keep this folder when moving the installation: it is not included in the database backups below. Stop Even Keel before copying it. If it is lost, Even Keel recreates it from the rows retained at the original migration; later machine-only changes and pending messages are lost.
An Even Keel from before it kept them in a SQLite file state/even-keel.db or, earlier, in files: the first start of this version imports even-keel.db, or else chain.json, questions.json, launches.jsonl and handoffs/, in one go — all of it or nothing — and renames them to <name>.imported.
The config file even-keel.config.json is imported the same way, once, and kept as even-keel.config.json.imported; a file put there later is not read (the log says so).
A database written by a newer version leaves the service with only the page, like a newer file.
If another process holds the database when Even Keel starts, the page names that process and the service waits, trying again every 3 seconds.
Wait for a backup or another reader to finish, or close the other Even Keel instance.
Once the database is free, the service starts and the page reconnects automatically; no restart is needed.
A different storage error stays on the page until it is fixed and the service is restarted.
This copies the hub database and the built-in tracker’s attachments, also while Even Keel runs. For a move, keep .env, state/machine/ and the agent account folders as well:
npm run storage -- backup <new folder>To restore, stop Even Keel and put the folder in place of state/even-keel.
Even Keel also makes such a copy itself: once a day, and at the start of a new version before it changes the database.
Each copy is opened back in a temporary folder and compared with the database before it counts; one that does not open whole is removed, and a failure shows a banner on every page while the older copies stay.
The copies go into state/backups/, next to state/even-keel/, named even-keel-auto-<date>-<time>-v<schema>, and the newest 14 are kept.
Settings → Backups shows the last checked copy, makes one at once, and sets Copies folder (backup.dir, an absolute path; a folder on another disk survives this one) and Copies to keep (backup.keep, 1–365).
Folders of other names in it, such as your own backups, are never removed.
A copy holds the trackers’ tokens and keys in plain text: keep its folder as private as .env.
To restore one, stop Even Keel and put it in place of state/even-keel, as above.
The statistics database is versioned too: the collector brings its schema up to date on its first run after the update, step by step, each step in one transaction.
Going back to an older version does not undo that: the older collector stops on a newer database (one line in the log) and /stats says so, until you update again or restore a backup of the database taken before the update (<state>/tally/pgdata for the embedded one).
On your own Postgres the collector migrates as tally_writer; if it is not the owner of the tables, it changes nothing and logs the statements to run and the role to run them as.
Going back
Section titled “Going back”After an update from the page that kept the storage format, Revert in the update window does all of this. Otherwise, by hand:
- Stop Even Keel (as a service: stop the service). Stop it first: a running Even Keel may write over the restored files.
- Check out the previous version’s code (
git checkout <commit>). - Put the
.bakcopies back in place of the rewritten files. - Start it again (as a service: run its install script).
What the newer version wrote since the update — launches, the chain’s state — goes with the .bak. The checkout leaves git on a detached commit, so the next update starts with git checkout main before git pull.
To go back to a version from before the database, stop Even Keel and export the state into an empty folder and the config into its old file, then put the exported state files into state/ before starting the old version:
npm run storage -- export <empty folder>npm run storage -- config-export even-keel.config.jsonUninstall
Section titled “Uninstall”Remove the service — besides it, only the hook Even Keel added to the settings.json of its Claude account folders goes:
even-keel uninstallFrom a clone, on Windows:
node dist/src/cli.js uninstallOn Linux and macOS:
service/uninstall.shOn Windows it removes the start at sign-in with its host, and the Windows service too if there is one; that part needs PowerShell 7 as administrator (a clone: service\uninstall.ps1).
Sessions it started keep running: they belong to the CLI’s daemon, so finish or stop them first (claude agents lists them). The rest stays where it is, for you to remove by hand.
Installed with npm: the package, then the data folder (above), which holds everything listed for a clone’s folder below.
npm uninstall --global even-keelA clone: delete its folder. It holds the code, .env with the tracker credentials, the config, logs/ (Windows and macOS; on Linux the log is the journal), and state/ (EVEN_KEEL_STATE_DIR) with:
- the state database,
state/even-keel/: the chain, the launch log, closed tasks; - the installed packages,
state/packages; - the embedded statistics database,
state/tally/pgdata. On your own Postgres the statistics stay in that database.
In each project’s repository:
- the worktrees of unfinished tasks in
.claude/worktrees/with their branches<key>-<number>/task(git worktree list, thengit worktree removeandgit branch -d), and the slots of a project withslot; - the lines
.claude/worktrees/,.temp/and/.codex/rules/even-keel.generated.rulesEven Keel added to.git/info/exclude, and that rules file itself; - with the plugin:
claude plugin uninstall huly@even-keel --scope project(orgithub@…,linear@…,gitlab@…,jira@…,forgejo@…), then commit.claude/settings.json.
In your Claude Code config and the other agents’:
- the plugin credentials in the
envof~/.claude/settings.json, and the marketplace (claude plugin marketplace remove even-keel); - the extra Claude account folders in
~/.claude-accounts(EVEN_KEEL_ACCOUNTS_DIR), each still signed in until you runclaude auth logoutwith itsCLAUDE_CONFIG_DIR; - the Codex ones in
~/.codex-accounts(EVEN_KEEL_CODEX_ACCOUNTS_DIR) the same, withcodex logoutand itsCODEX_HOME; - the OpenCode ones in
~/.opencode-accounts(EVEN_KEEL_OPENCODE_ACCOUNTS_DIR), whose credentials are indata/opencode/auth.json: deleting a folder signs it out; - the GitHub Copilot ones in
~/.copilot-accounts(EVEN_KEEL_COPILOT_ACCOUNTS_DIR), each aCOPILOT_HOMEof its own; - project memory, moved to
~/.claude-memory/<project>with~/.claude/projects/<project>/memorylinking to it: Claude Code keeps using it through the link, so leave it unless you want the memory gone too; - your skills, moved from
~/.claude/skillsto~/.claude-skills/<name>the same way, each leaving a link behind, and so~/.claude/agents,commands,hooksandoutput-styles, to~/.claude-agentsand the like: leave them, or move the folders back in place of the links.
The CLIs it depends on
Section titled “The CLIs it depends on”Even Keel drives the agents’ CLIs through behaviour none of them documents, so a CLI update can break it. This section lists what it relies on in each CLI, where it finds the binaries, and how the Checked version is downloaded and pinned.
Claude Code
Section titled “Claude Code”Even Keel depends on undocumented behaviour of the Claude Code CLI: claude agents --json, the sessions/<pid>.json records and the jobs/<id>/state.json job files, the background daemon (claude --bg, --bg --resume, claude daemon), the transcript format, the text of /usage, the layout of ~/.claude.json, .credentials.json and plugins/installed_plugins.json, and on macOS the name of the Keychain item that holds a folder’s sign-in. None of it is a public API.
A version becomes the checked one after one live session on it went through a launch, a question answered from the chat, the chat’s feed, a checkpoint and a stop (npm run cli-check, docs/releases.md).
By default chain sessions run on your own CLI, on whatever version it has updated itself to, and the event log (Log in the header) gets a warning when that is another version than the checked one: the stage, the context fill or a limit may then be read wrong, at worst a session does not start.
“CLI version” Checked (in the setup’s Agent step or Settings → Providers and models, which the log’s warning opens) runs them on the checked version instead: Even Keel downloads it from Anthropic into state/cli/claude/<version>/ (~340 MB a version, checked against Anthropic’s sha256) only after you press Download, waits for that copy before starting chain sessions, and turns the auto-updater off for those sessions so they never update your own install (docs/sessions/cli-versions.md).
Installs from before v0.2 stay on Checked. The pin has limits:
- A session runs on the version of its account folder’s daemon. A daemon on another version is restarted only once no session of that folder is live, and a newer
claude --bgorclaude agentsrun in the same account folder replaces the pinned daemon with its own version: keep your own background sessions out of the chain’s account folder. Whether a terminal reaches the service’s daemon on Windows to do that has not been checked. - Anthropic’s servers may refuse an old version, and an old version may not know a new model’s alias; Codex lists models by the client’s version. Then the checked version is raised in a new release of Even Keel.
- The transcripts your own sessions write on a newer version are read as before: the pin covers how chain sessions are run, not those files.
The same goes for the Codex CLI: the events of codex exec --json (thread.started, item.completed, turn.completed, turn.failed), -c overrides of its config keys (mcp_servers, marketplaces, plugins, hooks.state), the rollout files sessions/YYYY/MM/DD/rollout-*.jsonl and their session_meta, turn_context, event_msg (token_count with the context fill and the rate limit windows, task_complete, errors) and response_item lines, the plugin/install and hooks/list calls of codex app-server, the [plugins.*] tables of config.toml and the plugins/cache layout, the claims of the ID token in auth.json, the text of codex login status and of its quota errors, and the layout of the npm package on Windows.
With Checked, Codex sessions run on the checked version the same way: Even Keel unpacks the platform’s npm package @openai/codex@<version>-<platform> (Apache-2.0, checked against the registry’s sha512) into state/cli/codex/<version>/.
Where Even Keel finds the CLIs: Claude Code’s native install in ~/.local/bin (claude.exe on Windows), then the native binary of npm install -g @anthropic-ai/claude-code, then the binary of the VS Code extension, then claude on PATH; EVEN_KEEL_CLAUDE_BIN overrides. The page suggests the native installer (curl -fsSL https://claude.ai/install.sh | bash, on Windows irm https://claude.ai/install.ps1 | iex in PowerShell): a newer npm skips the package’s postinstall unless allowed, and then claude in a terminal prints “claude native binary not installed”, though Even Keel still finds the binary inside the package.
Codex’s own folder is CODEX_HOME or ~/.codex, the accounts added from the page live in ~/.codex-accounts; EVEN_KEEL_CODEX_BIN overrides the binary.
OpenCode
Section titled “OpenCode”OpenCode too: Even Keel relies on the JSON events of opencode run --format json, its -s and --title, OPENCODE_CONFIG_CONTENT, the XDG folders, auth.json, the tables session, message and part of opencode.db, and the text of opencode providers login.
With Checked, its sessions run on the checked version: Even Keel unpacks the platform’s npm package of its native binary (opencode-windows-x64@<version> and the like, MIT, checked against the registry’s sha512, ~80 MB a version) into state/cli/opencode/<version>/, with self-update turned off.
An x64 processor without AVX2 needs OpenCode’s -baseline build, which Even Keel does not take: keep its “CLI version” on Yours there.
With Yours, sessions run on the opencode you installed (npm install -g opencode-ai; Even Keel takes the native binary inside the global npm package, also when npm skipped the package’s postinstall); EVEN_KEEL_OPENCODE_BIN overrides both.
Its accounts live only in ~/.opencode-accounts: your own OpenCode’s folders are not listed.
GitHub Copilot
Section titled “GitHub Copilot”GitHub Copilot too: Even Keel relies on the JSONL of copilot -p --output-format json, its --session-id, --resume, --no-ask-user, --add-dir, --additional-mcp-config, --disable-mcp-server and --plugin-dir, COPILOT_HOME and COPILOT_GITHUB_TOKEN, and the events of session-state/<id>/events.jsonl.
With Checked, its sessions run on the checked version: Even Keel unpacks the platform’s npm package of its native binary (@github/copilot-win32-x64@<version> and the like, checked against the registry’s sha512, ~155 MB a version) into state/cli/copilot/<version>/, with --no-auto-update and COPILOT_AUTO_UPDATE=false.
With Yours, sessions run on the copilot you installed: on Windows Even Keel finds by itself the copilot.exe of winget install GitHub.Copilot and the native copilot.exe of npm install -g @github/copilot (npm’s own copilot wrappers need a shell and are not run); EVEN_KEEL_COPILOT_BIN overrides both, for a binary installed anywhere else.
When the binary cannot be started, the chain pauses and says so, with a button to the CLI version setting.
Sign in once with copilot login, or add accounts with tokens on the accounts page.
Its accounts live only in ~/.copilot-accounts: your own ~/.copilot is not listed.
Copilot’s own sign-in on Linux without a keyring
Section titled “Copilot’s own sign-in on Linux without a keyring”On Linux without a keyring, Copilot’s own sign-in needs a terminal and the managed account’s folder.
When the CLI confirms that folder is signed out, the accounts page shows a copyable command using its folder and the same CLI binary as sessions.
Run it on the machine running Even Keel, as the same OS user: in cmd on Windows, standard sh on Linux/macOS.
The command temporarily removes COPILOT_GITHUB_TOKEN, GH_TOKEN and GITHUB_TOKEN and selects the account’s COPILOT_HOME; your terminal’s environment stays intact after success or failure.
The CLI asks whether to save the token as plaintext in that folder’s config.json when no keyring is available.
Login without COPILOT_HOME saves into your own ~/.copilot, which managed sessions do not read; login without a terminal may report “token was not saved” without asking about plaintext.
The card updates after the next account check, without restarting Even Keel; restarting also checks again.
An unavailable CLI, timeout, empty or unreadable status shows “Could not check” and allows sessions to start. An explicit signed-out answer shows “Sign-in needed” and the command; a successful check clears the warning.
You can instead add a token through the accounts page; a folder’s own token takes priority over the machine’s sign-in. A successful own OAuth sign-in has no remaining-allowance bar.