Repository navigation
Releases
SAKO 0.7.1
The method, the reference pages, the recipes, the glossary, the skill and the README describe what 0.7.0 added, and a test that failed on native Windows passes there. Runtime behavior is the same as in 0.7.0. SAKO remains alpha software.
From your project's Git repository, install with uvx sako@0.7.1 init, or update an existing installation with uvx sako@0.7.1 init --update.
To update from 0.7.0, run init --update between working sessions, in the main checkout, then run verify when a check is configured, since the new version makes every recorded pass stale. From 0.6.0, follow the steps in the 0.7.0 release first.
Changed
- SAKO.md describes
edit, the session's own rows and its peers' progress, named checks, a pass from another worktree and the advice for a file rewritten after its close. It also says a receipt cites a lasting home, an unmet part of a done-when becomes a new task, task IDs come fromadd's output, and an edit after a close is new work. - The limits, validation and compatibility pages cover the same additions and their limits, with fresh counts.
- The intake recipes add a review's findings, the owner's own acts, a row moved from another ledger and an act only one session may do at a time, and show how to capture a new task's ID. The glossary defines Marker, and the skill names
edit. - README's principles section is "Simple, not small", and README names
edit, named checks, peers' progress and a pass from another worktree where a reader needs them. The tracker recipe parks rows withedit.
Fixed
- A test of the start context compared the header's middle dot, which native Windows reads back in its code page, so the test failed there.
Validation
- Both suites pass on Python 3.10 and 3.12 locally, with 277 tests and 22 scenarios; these counts overlap.
- Natively on Windows from Git Bash, with Python 3.14.4 and Git for Windows 2.52.0, 277 tests ran with 46 skipped and the scenario suite passed 17 and skipped 5, with none failed.
SAKO 0.7.0
Agents change rows through a command instead of by hand, sessions see each other's progress, a pass in one worktree proves identical content in another, and named checks sit beside the gate's check. A stop that the gate cleared by mistake when the clock stepped back now blocks. The runtime may grow to 4,000 lines and wraps at 100 columns. Task records from 0.6.0 still parse. SAKO remains alpha software.
From your project's Git repository, install with uvx sako@0.7.0 init, or update an existing installation with uvx sako@0.7.0 init --update.
To update from 0.6.0, follow these steps:
- Update between working sessions, in the main checkout. The hook command is the same as in 0.6.0, so Codex keeps its trust in SAKO's hooks.
- End any session left open across the update, then start it again with the same ID, which keeps its claims and takes a new start record, or start a new one.
- Run
verifywhen a check is configured. The new version makes every recorded pass stale.
Added
edit T-nchanges a row under the ledger lock: its scope (--scopereplaces,--widenadds), its prerequisites (--after, where-clears them), its done-when, or its state (--park REASON,--open). A claimed row is edited only by its holder, a path new to its scope faces claim's overlap rule, and the edited row passes the row checks or nothing is written. Task and Pri stay hand edits, and a done row stays as history.- Named checks.
config.jsontakeschecks, a map of names to argument arrays over the sameverify_paths.verify NAMEruns one and keeps its own stamp and logs,statusshows each as fresh, stale or none, and a close addsNAME pass TIMEfor each fresh one. A named check is evidence, never one of the gate's rules. - A pass recorded in another worktree or in the main checkout counts when its content and command match this checkout's, and
status,startand the receipt say where it ran. - Start, resume and compact contexts list the session's own rows with their handoff state and scope, and the header names the start revision. Each live peer's line shows its commits since its start and its uncommitted paths in its own checkout, read within 2 seconds. In the repo footprint,
statuslists the records committed since you started.
Changed
- Refusals and findings that sent an agent to hand-edit
.sako/work/TASKS.mdprint aneditcommand instead: claim's overlap and missing-scope refusals, the parked refusal, the stale-claim finding and the gate's own overlap finding. - A closed task's file rewritten after its close, as by a stash, a Git hook, a formatter or an editor save, is listed under Recorded with the task that closed it, and the fix says to commit it under that task's title when the content is still its work.
- The Proven rule counts only the gate's own check pass in a receipt, never a named check's. A close whose receipt shows that pass stays proven while only others moved checked content since the session started.
- The note for a path claimed by a peer in another worktree says its work counts here once merged, and
removenames a linked worktree's tracked Codex settings file in full. statussays "landed in the code since you started".- The runtime cap is 4,000 lines, and no line of
sako.pyruns past 100 columns.
Fixed
- The gate dropped a commit made just after the session started when the wall clock stepped back, as WSL's can by a second or two, and could clear a stop it should have blocked. It now lists the session's commits from a minute before its start, still bounded by its start revision. The records line in
statuslooks back 5 seconds. verifytimed its run by the wall clock, so a clock stepping back could print a negative time such asPASS in -1s. It uses a monotonic clock.
Known issues
- A live peer in the same checkout can claim a scope that covers this session's closed files. This session's edits and commits there then count as the peer's under Recorded and Proven for as long as the peer is live. The peer's own close still needs a fresh check.
- Two ended sessions holding overlapping claims still need a hand edit of the ledger, since neither claim can be taken over while they overlap.
- One test of the start context fails on native Windows, where the header's middle dot reads back in the code page. The runtime is not affected, and 0.7.1 fixes the test.
Validation
- Both suites pass on Python 3.10 and 3.12 locally, with 275 tests and 22 scenarios; these counts overlap.
SAKO 0.6.0
Sessions that share a checkout hold each other up less, and the records say more. Another session's stale claim or overlap no longer blocks a stop as a ledger finding, a closed task no longer covers later edits in its scope, records-only tasks close without the product check, receipts carry times and the checked commit, verify keeps its last pass and the check's output, and Claude Code's hooks find the kit from a nested repository. The method, the skill and the docs follow the runtime, and task records from 0.5.1 still parse. SAKO remains alpha software.
From your project's Git repository, install with uvx sako@0.6.0 init, or update an existing installation with uvx sako@0.6.0 init --update.
To update from 0.5.1, follow these steps:
- Update between working sessions, in the main checkout. There
init --updatealso gives each linked worktree that has SAKO's hooks the new hook command and keeps its other entries. A worktree without them gets none until you runuvx sako@0.6.0 initin it, and a tracked settings file there is left unchanged, with a note that names the file in full and gives the content to write. - The hook command changed for both clients. When the shell's folder leads to no kit, it looks again from the folder Claude Code names in
$CLAUDE_PROJECT_DIR. Codex records trust against each hook's hash and skips changed hooks until you trust them, so open/hooksin Codex and trust SAKO's hooks again. - End any session left open across the update, then start it again with the same ID, which keeps its claims and takes a new start record, or start a new one. Until it ends, it keeps its start record, and every file with the owner's executable bit that was already uncommitted when it started reads as changed by it. On Windows, Python reports
.bat,.cmd,.comand.exefiles as executable. - Run
verifywhen a check is configured. The new version makes every recorded pass stale, with the reason "the check command or paths changed since the last pass". - If a skills tool or a hand edit left a copy of the skill in
.agents/skills/sako/or.claude/skills/sako/that differs from the one SAKO installed and from this release's,init --updaterefuses with "has local content" and changes nothing. Keep what you need from that copy, delete it, and update again. A copy tracked in Git is left unchanged, with a note, so update it yourself.
Added
- Records-only tasks, whose every scope entry lies in
.sako/, close without a fresh check while only others moved checked content. Their receipt says "no automated check (records only)", and the Proven rule skips them while that holds; Recorded and Committed still apply. Others' changes are edits left uncommitted before your session started, committed since or not, and edits or commits in the scope of a task that a live peer in this checkout claimed, or closed no earlier than the minute the file last changed. Any other commit since your start, and a merge, pull or checkout of older commits, counts as yours. verifywrites the check's output toverify.logbeside the stamp and prints it when the check ends, instead of as it runs. A failed run's output also goes toverify-failed.log, which a later pass leaves in place. The PASS and FAILED lines name the log.addnames each claimed row that the new task's scope overlaps, with its holder's marker.- One
--scopetakes several paths, and the repeated form still works. A task text placed right after a scope path fails with a usage error and adds nothing. - Each verb's
--helpsays what the verb does.
Changed
- Of the ledger findings, the finish gate blocks only on a duplicate ID, a source mapped twice, a faulty row and an overlap with one of the session's own claims. Footprint findings and the three rules block as before. Other sessions' stale claims and overlaps print as
note:lines after the verdict ofcheck --gate, each with its fix, and a clear stop through a hook stays silent.start,statusand plaincheckstill list every finding, those about other sessions last. claimwrites "since" and the time, to the minute with its zone, after the marker in Status.closecarries that marker and time into the receipt, so a session that resumes on a later day closes under the marker it claimed with, and writes the close time where it wrote the date. A check pass in a receipt names the commit the check ran at, with "plus uncommitted changes" when the checked files differed from it.- An overlap refusal from
claimnames the other claim's scope and holder and the ledger file where a Scope can be narrowed, with a next step that fits that holder, such as waiting for a live one or taking a stale one over first. A parked row's refusal names the Status edit that reopens it. From a linked worktree, these refusals and the one for a missing row give the ledger's absolute path. - The claim printout and the handoff advisory say that if this session ends before closing the task, its claim reads as stale and another session may take it over with a reason. The stale-claim finding also offers parking the row.
- Peer lines show the last 8 characters of each peer's session ID and list only its claimed rows, under one header with the advice for a peer with no claim.
startandstatuslist each handoff folder once, and a closed task's remaining one for every session, marked "(closed: delete)". statusnames the commandverifyruns, and so do the evidence line,close's refusal and the gate's Proven finding when no pass is recorded. The changed-this-session line and the clear line ofcheck --gatename the checkout they judged.- The start context, and the line
initgives for project instructions, say to read SAKO.md down to its Read when needed table and later sections only when they apply, and that questions need no task record until they change a file, withaddandclaimbefore that change. The start context labels its pick "next, if no task was named for you", and its marker line drops its hint. - Each "not counted" note of the gate names at most three paths, then "and N more", and the sentence that a shared checkout shows what changed, not who changed it, comes once, as its own note.
- The Committed fix for product files suggests the task's title as the commit message, without the task ID.
endprintssako: presence ended, orsako: no presence entry for this session ID; nothing ended. When removing the entry fails, as in a kit folder a sandbox keeps read-only, it exits 3 with the reason instead of passing silently. The session end hook still exits 0.init --updatein the main checkout also refreshes SAKO's hook entries in each linked worktree that has them, keeping the other entries there. A linked worktree's settings file that holds SAKO's entries but does not parse stops the update before anything is written.- A tracked client settings file is still left unchanged, and the note
initprints for it now gives the content to write there, SAKO's hooks included, and names the file in full when it is in another checkout. When SAKO would take its hooks out of such a file, as when a client is dropped, the note says to remove them there yourself and gives the content without them. The line that lists the wired clients beginsHooks:instead ofHooks written:, since a tracked file gets none. removealso deletes the client folders it leaves empty, such as.claude/skills/, so a laterinitno longer detects a client from them, and its last line says that SAKO's lines in.git/info/excluderemain to delete. It now prints the note for a tracked settings file, which keeps SAKO's hooks until you remove them there.- The finding for a stray
.sako/in a linked worktree says to move or delete it. - The method and the skill say to read SAKO.md down to its Read when needed table and that questions need no task record until they change a file, with
addandclaimbefore that change. The skill namesuvx sako initfor a project without.sako/and drops the check-in paragraph that the daily loop holds. The method follows the runtime throughout, including how to park an owner's step or deferred work as its own row, what leaving, a resume,/clear, a fork and a restart do to presence and claims, and which session ID a subagent uses. - The limits page names the limits that remain in local coordination. The compatibility page says that a subagent's shell carries its parent's session ID, that Codex runs hooks only after you trust them in
/hooks, again after each change, and records what background/exitand resume did in use. The update page covers linked worktrees, a session left open across an update, and rollback. SECURITY.md lists everything a hook orinitreads, and the glossary, the validation page and the README match the gate and its receipts. - CONTRIBUTING.md welcomes pull requests that agents open on their own, when they name the tool, show the checks and answer review. AGENTS.md covers work from a fork, a pull request template asks for the issue, the change, the check output and the AI tool used, and the README shows badges and points to good first issues.
Removed
- The ledger finding that a task was claimed before its prerequisites were done.
claimalready refuses such a row, andnextlists waiting rows with their reasons.
Fixed
- Claude Code's hooks work from inside a nested repository, such as the repo footprint's
.sako/repository. The hook command looks for the kit from the current folder, then from$CLAUDE_PROJECT_DIR, and runs SAKO from where it found the kit. Before, the hook exited 1 there and the stop went ungated. Codex names no project folder, so a Codex hook there still exits 1, now naming the folder it searched and how to recover. - On Linux and WSL a restart ends presence. A presence entry records the machine's boot, so after a restart it no longer counts as live through a reused process ID or a sandbox entry...
SAKO 0.5.1
A clearer first page and session check-in wording. Runtime behavior, commands
and task record formats are unchanged. SAKO remains alpha software.
From your project's Git repository, install with uvx sako@0.5.1 init, or
update an existing installation with uvx sako@0.5.1 init --update.
Added
- A README storyboard from a reproducible two-session example, with its full
command transcript and checks that keep it current. - A compact diagram of how SAKO fits a project, with editable visual sources.
Changed
- A shorter README organized around getting started, working with parallel
agents, and bringing clarity to an existing project. - The method, skill and demos describe
startas registering an existing agent
session. Your coding tool launches agents; SAKO coordinates their task records
and checks.endclears presence without stopping the agent process.
Validation
- Both suites pass on Python 3.10 and 3.12 locally, with 180 tests and 22
scenarios; these counts overlap. - CI checks Python 3.10 and 3.14 on Linux, macOS and Windows, plus package
building and installation. The known platform limits remain.
SAKO 0.5.0
The first public release.
Install from your project's Git repository with uvx sako init. To update later, run uvx sako@latest init --update.
Added
- A task ledger in Markdown,
.sako/work/TASKS.md, with a done record that keeps a receipt for every closed task. - A finish gate that checks, when a session stops, that its changes belong to a claimed task, that closed work has a passing check for its content, and that finished work is committed.
- Hooks for Claude Code and Codex, chosen by
init; any other agent runsstart,check --gateandenditself. - Claims and scope checks for parallel sessions in one repository and its linked worktrees.
- Three footprints for the records: local (the default), their own repository, or committed with the code.
- The method,
SAKO.md, with a small default planner, and asakoskill for agents.
Known issues
- Codex gets no hooks on Windows; there the agent runs the commands itself.
- No live client session has run on a Mac yet; macOS is tested in CI.
- See limits for the rest.
Tested with
- Python 3.10 and 3.14 on Linux, macOS and Windows in CI; Python 3.10 and 3.12 on WSL2 (Ubuntu 24.04).
- Git 2.31 or newer.
- Claude Code 2.1.280 on Linux and Codex 0.154.0 on Linux; Claude Code 2.1.220 hooks on Windows.