AI agents can write code. But who keeps the work moving when sessions end, tests pass on the wrong version, or agents step on each other?
This is why I built OwlRunKit. https://x.com/i/article/2118990534362488832
Introducing OwlRunKit: A Project Driver for AI Agent Work
I’ve always worked on the technical side. I’ve never released a product before, and honestly, I don’t really know how to launch one.
OwlRunKit is the first component I’ve released myself. I’ve been using it in my own work for at least six months, and I’ve found it very useful. But I never quite knew how to introduce it to other people.
Recently, I started sharing some of the problems we often run into and the ways we deal with them. In those conversations, I realized that quite a few other people were facing the same problems.
That’s why I decided to put together this introduction: to explain what OwlRunKit actually does and how it can help.
The repository is here: https://github.com/yeemio/owlrunkit
What is OwlRunKit?
OwlRunKit is a project driver and verification toolkit for software work involving AI agents. It organizes the project facts recorded by the caller, selected code changes and verification evidence so that another session or executor with access to those materials can inspect the work and continue from it.
It is useful when questions like these start appearing:
- An agent stops halfway through. Where does the next session find the current task and the next action?
- Two agents are working on different things. Are they about to edit the same files?
- A test passed, but the code or configuration changed afterward. Which version does that result belong to?
- Another person receives a receipt. Can they actually get the code and output needed to check it?
- The work items are complete. Has the change also been integrated, deployed and accepted by the person who needs it?
You do not need a large team of agents to have these problems. A single developer handing work from one session to the next can use a project record; a small, low-risk check can start with one command and a receipt. More demanding work can use stronger verification and explicit delivery gates.
OwlRunKit is a locally used package, not a service that automatically launches every model or synchronizes every machine. A person or an existing execution environment still needs to start the relevant agent and make the project records and files available to it. The toolkit keeps the work and evidence organized once those connections exist.
The system at a glance
At the center is the project workspace. The command-line interface records project facts and produces views of the current work. Candidate tools can freeze selected changes or reconstruct them in a suitable checkout. Verification tools can run chosen commands and save their results. Delivery records let us describe how far the work has progressed.
The agents, schedulers, actual project commands, target workspaces and external systems remain distinct. Some commands only read a view; others write records, run a real program or write files into a target. A record saying a deployment happened is different from the deployment itself.
Figure 1. OwlRunKit keeps project and verification records and can reconstruct a bounded candidate when invoked. The people or environment running the agents must arrange access to the records and actual files. This is a source-based schematic, not a screenshot of a completed run.
How the project organizes its information
A project begins with a definition. It names the objective, milestones and workstreams, then breaks the work into work items. An item can declare its dependencies, the paths it owns, measurable units where they make sense, and conditions that must be met before integration.
As work happens, the caller records facts: an assignment, a checkpoint, a handoff, a decision, a failed attempt or a return for rework. OwlRunKit uses the definition and those events to calculate the current view. The next executor can ask for project status to see owners, waiting work, dependencies and gates. project takeover adds information about the current candidate, relevant changes and handoffs superseded by later facts.
A handoff record says who is expected next and what they should inspect or do. Reading that record does not start the next agent or prove that it has accepted the task. The next assignment has to be recorded, and the executor must actually be given access.
Figure 2. The definition describes the work; recorded events add facts; status and takeover derive a current view. A reference to a candidate or evidence file does not itself copy the file or grant access.
The files make that structure concrete. Depending on the features used, a project can contain:
.owlcoda/runkit/
project/definition.json Project goal and work structure
project/events/ Assignments, checkpoints, handoffs and decisions
executions/<run-id>/ Optional execution, lease and candidate records
quick/receipts/<receipt-id>/ A receipt and its saved command output
An execution is optional for a work item. Inside an execution, a SourceCandidate V2 can have a candidate document and a separate payload directory containing selected file bytes. A Quick receipt directory can contain receipt.json, stdout.log, stderr.log and, when used, a saved input file. These are different objects with different jobs. A path or hash in one record tells you what to look for; it does not put the referenced file on another computer.
The current project view is derived from recorded facts. It is not a backup of every conversation or a promise to recover a model’s hidden state. If a decision, file or constraint was never recorded, the next session cannot recover it from the project ledger by magic.
From an assignment to a handoff
Imagine a small checkout fix. One agent updates checkout.js, adds a helper and changes an existing test. The changes are not committed. A separate notes.md in the same checkout belongs to someone else. This is an illustrative example, not a production incident or a run performed for this article.
The project definition can assign the checkout and test paths to a work item. The implementer records a checkpoint describing what changed, where the materials are, and what remains. When the candidate is ready, a handoff can name a reviewer and ask them to inspect the requirement and run the relevant checks. The successor reads status and takeover, then the work is assigned to that successor; the act of displaying a takeover view does not itself acquire write authority.
If another writer wants an overlapping path at the same time, declared assignments and writer leases can expose and reject conflicting active claims. That allows the work to be narrowed or sequenced while unrelated tasks continue.
In the discussion on the write-scope post, Ganesh made an important distinction: what changed since the worker arrived, were the changes within the approved scope, and could a process bypass the coordinator and write elsewhere? These need separate evidence. A lease coordinates participating writers; it is not an operating-system lock on every process. An entry snapshot can help compare the state before and after external work, but it cannot prove which process made a change or reveal a change that was made and then restored between observations.
If the handoff goes directly from the implementer to a verifier, the Project Driver’s verifying transition checks that the currently declared agent ID differs from the immediately preceding assignment. Some Team acceptance checks also examine declared model families and fresh checks. These are checks on recorded declarations, not authentication of the actual person or model. The people or environment coordinating the work must still arrange a real, independent review.
Moving the actual candidate
In the checkout example, copying only checkout.js would omit the helper and the updated test. Copying the whole directory could bring along someone else’s notes or secrets. I used a similar scenario in this post on moving uncommitted changes, with a deleted test rather than an updated one.
For a bounded set of uncommitted changes, SourceCandidate V2 can freeze a candidate under an active execution and lease. It records the Git baseline, allowed paths and a manifest of changes, and it stores actual payload bytes for the selected files. In this example the receiver can get the updated checkout file, helper and test while leaving notes.md out of the candidate.
The receiving checkout must meet the documented conditions, including a clean target at the same Git HEAD. Materialization verifies and applies the candidate through a staging checkout and writes the target. This is a real file operation, so protect existing work first. A clean Git status does not mean there are no ignored files; inspect and protect those separately before writing to the target. A selected path may itself contain credentials, so inspect and handle sensitive material before freezing it. The candidate is not the whole repository, installed dependencies, ignored fixtures or external service state; those inputs must be arranged separately.
There is also a difference between a delivery packet that identifies material and a SourceCandidate V2 payload that contains selected bytes. A reference or hash does not transfer those bytes. If agents are on different machines, the people or environment responsible for the task must arrange an authorized way for the relevant records, payload and baseline to be read.
Running checks and preserving the evidence
Once the second executor has the candidate, it can review the requirement and select checks. A verification profile can map changed paths to groups of commands and declared dependencies. If a changed path is not covered by the mapping, the system can require a full-profile decision. It does not infer every hidden dependency in the code, and choosing a check does not run it.
Quick runs a command the caller chooses. It records the command and working context, captures relevant workspace identity before and after, and saves the exit result and stdout/stderr. The resulting receipt helps a later reader connect that run to the materials it actually binds.
That addresses a question E1ev3n raised after my post about testing the right version: a green result is not useful if it belongs to the wrong build. A source fingerprint identifies the source within its scope; if the real question is which compiled artifact or running service was tested, that artifact and target need their own evidence too.
For a separate target checkout, the documented --foreign-workspace Quick path can run the command in a temporary copy of the target’s Git-visible files while keeping the receipt and output in the project controller. The controller and target must be distinct real directories, neither containing the other, and the target must be a Git worktree root. Both must be accessible to the same correctly bound RunKit process. Dependencies and ignored fixtures may need separate preparation. This is a local path interface, not a protocol that automatically transfers work between machines.
One version-specific limitation deserves care. The current candidate materialization code can remove a tracked file while Git still lists its path; the temporary-copy code may then encounter a missing file before the test starts. That is a static inference, not a failure reproduced in OwlRunKit. The checkout walkthrough uses an updated test rather than a deletion, and the whole walkthrough has not been run for this article.
Where appropriate, a receipt can be bound back to a project checkpoint using project checkpoint --from-quick-receipt; that path first requires a GO attestation and the relevant bound materials to remain available and matching. GO is a decision under that check’s contract. It is not proof of the author’s identity, a claim that every useful test ran, or permission to deploy.
Quick’s offline bundle carries the receipt bytes and a reference, not the whole workspace or full stdout/stderr files. In the discussion on this post, Olivia and Ken raised the obvious question: what can the next person really check without the output? Make the candidate, necessary output and environment details available through an appropriate channel, and say what is missing. Logs can contain secrets or personal information; Quick does not generally redact them for you.
A command can also fail before any assertion runs. Anika’s response to the sandbox post captured the risk: an agent sees exit code 1 and confidently changes code that may have been fine. Check whether the environment blocked a helper or temporary file before concluding that an assertion failed.
Visual checks have their own gap. In the signup-page discussion, Bobo pointed out that an assertion ID could match a manifest without catching a real layout problem, and suggested tying the visual output requirement more closely to that manifest. That is an improvement suggestion, not a feature I am claiming is implemented. The current visual-smoke code checks an external runner’s report and artifacts; it does not itself look at a screenshot or establish that a person reviewed the layout.
For higher-risk work, Formal adds a stricter execution and evidence contract where supported. The specific Formal V2 enforcement backend in this version depends on macOS sandbox-exec; it should not be described as the same enforced sandbox on every platform. Quick’s temporary copy is useful, but it is not an OS-level sandbox.
Continuing work and reporting delivery
A saved project can help another session find its goal, current owner and next action. The bounded recovery view labels project text as data to examine, not fresh permission. In the compaction discussion, XiangShi pointed out why that matters: an old note saying “already approved” could otherwise be mistaken for permission to deploy today.
There is also an optional Codex Stop hook that can watch bound project data while the same turn is still waiting. A change can request a continuation, after which the agent should read the actual status and material. In the discussion on the Stop hook post, Shaoze asked what happens when the other worker takes longer than the ten-minute wait. The hook stops waiting and cannot restart a turn that has already ended. A separate trigger would be needed for a later turn; the timeout-to-new-turn connection was not established in that discussion.
When the work items are complete, the project can still have several distinct delivery stages: source, integration, materialization, deployment, live readback and product acceptance. Their records have prerequisites and evidence references. Recording those stages does not automatically perform a deployment, observe the live service or decide business acceptance. An optional deployment path exists for properly authorized work with the required authority and adapter; an unknown remote outcome must be checked rather than blindly retried. A journal does not guarantee exactly-once execution.
Kien asked how we know an agent loop is actually finished. In my reply, I said to look for the agreed outcome and evidence that it was checked. If the loop stopped without those, it is stopped or blocked, not finished.
One real handoff: Dots and Grokbot
I have used a broader setup in which Dots and Grokbot worked from a shared task record. In the original introduction, I described OwlRunKit keeping the shared record while the two tools checked for work on their own schedules. In a later post, I described a task being assigned, picked up, returned with supporting material and reviewed. The mailbox in that setup was on my Mac, with each tool using its own scheduler.
One preserved October handoff involved revising Grok’s own execution and recovery guidance. The surviving materials include the task and assignment, a result report without an event timestamp, a handoff record and the receiving review. The producer reported the save and six static-rule scenarios. The receiving review recorded a comparison of the delivered source and diff, and accepted the text revision and reported scenarios with explicit limits.
We have the report and review conclusion, but not individual execution records for the six checks, so we cannot independently confirm that each was performed and passed. The records also do not establish what triggered that particular assignment, whether a later session loaded the new guidance, whether runtime recovery or cross-host MCP worked, whether a model woke, or whether the work received production acceptance.
Figure 3. A bounded historical task with an assignment, handoff and receiving review. The producer’s reported static scenarios and the review’s limits are shown separately. These records do not establish the trigger or later runtime behavior.
This example shows a real, traceable handoff, not proof that the current public release automatically connects all assistants or that the old configuration is running today.
Another real case: implementation, review and rework across tools
In another workflow, I have used ZCode with GLM 5.3 for implementation, a DeepSeek reviewer running in Cloud Code for review, and Codex to coordinate the outcome. One September development record identifies the writer as ZCode’s GLM-5.3-Flash and calls the reviewer “Claude-DS.” The reviewer’s original session and exact provider identity for that particular record have not been independently recovered, so those two descriptions should not be treated as the same kind of evidence.
The work was to improve an analysis application. The writer prepared a candidate for review with its source changes, a manifest, test output and recovery materials. The delivery record describes review findings: a candidate bundle had not caught up with regenerated source, and two end-to-end checks had been skipped. The controller chose to restore and strengthen the checks rather than lower the acceptance bar. Work then continued in the same candidate worktree, and the later path-and-hash changes were prepared for a focused review. The record requests that final delta review; I have not found independent confirmation that the request was delivered or a record of the review’s result.
An application’s later analysis may carry material forward from an earlier stage. If the original is unavailable or belongs to a different scope, it should not be treated as verifiable context. The restored checks exposed a concrete problem inside the application. Its two analysis stages were called T12 and T45; they are stages of the application, not names of the agents. Information from the earlier stage was supposed to be cleared when it was incompatible with the later one. A guard cleared it, but code below the guard rebuilt it and put it into two later request payloads. The repair moved that reconstruction under the compatibility check.
In the repaired application, T12 records each material’s ID, exact version and coverage scope. A test checks that, when T45 inherits context, it retrieves each recorded original. If an original is missing or unreadable, T45 refuses to inherit that context and returns MISSING_ORIGINALS; valid current materials can still be analyzed. A nonempty archive or a newer version is not enough to establish that the recorded original is available.
Those are two different flows. The candidate, manifest, review findings and changes went between the people and tools coordinating the development. The earlier-stage-to-later-stage material was data inside the application being tested. It was not the transport mechanism between ZCode and the reviewer.
The historical closeout log reports 555 tests passed, one failed and one skipped across 42 test files. It was not all green. The tests used controlled inputs and injected responses, not live paid-model calls or proof of business acceptance. The delivery described the remaining failure as pre-existing, but the separate baseline run has not been recovered here.
Figure 4. The historical record follows an implementation candidate through review findings, a controller decision and rework. Delivery and the outcome of the final delta review are not established. The separate inset shows application data under test, not the route used to transfer work between agents.
A contemporaneous record assigns maintenance of RunKit state to the owner/controller side. The preserved material establishes a real development handoff and rework, but we have not recovered a RunKit CLI or event receipt for this particular candidate. I cannot use it to claim that the current public Core automatically sent the package, authenticated the reviewer or accepted the review.
What is in the repository?
The public repository is the place to read the current source and documentation: https://github.com/yeemio/owlrunkit
A few parts are useful starting points:
- The root README and package describe installation, CLI entry points and the public release.
- scripts/runkit-contract/ contains the project, execution, candidate, verification, recovery and related control implementation. Its schemas and templates describe the inputs those commands accept.
- packages/attest/ contains the read-only evidence-checking implementation. The root package exposes owlrunkit-attest and the owlrunkit/attest program interface; do not assume that a separate package with a similar name is independently published.
- integrations/codex/skills/owlcoda-runkit/ contains the Codex Skill and supporting integration material. Installing the package does not automatically install or enable it in every agent.
- docs/architecture/ contains design decisions and historical contracts. A historical design document is useful context, but current behavior should be checked against the relevant release’s code and README.
The root package is licensed under GPL-3.0-or-later. Read the license and documentation for your use case.
How to start
Start with a disposable Git worktree of an npm project you understand, with a valid Git HEAD, a package.json and no work you need to preserve. Run the commands in this section from the worktree root. Before using the npm example below, check that packageManager in package.json specifies npm or is not declared, and that there are no yarn, pnpm, bun or other package-manager lockfiles. After installation, keep a single npm lockfile that matches the project’s package manager. For an existing project that uses another manager, do not copy these npm commands; follow its actual environment and the README instead.
The README currently identifies owlrunkit@0.24.1; the package requires Node.js 20.19.0 or newer. You also need Git, npm/npx and registry access. The registry’s current availability and these exact steps were not independently tested for this article.
From the project directory, the README’s exact-version installation and bootstrap preview are:
npm install --save-exact owlrunkit@0.24.1
npx --no-install owlrunkit bootstrap --workspace "$PWD" \
--exact owlrunkit@0.24.1 --dry-run
Installation contacts the registry and changes dependencies and lockfile material. The bootstrap dry run previews without writing project state, but it can read local data and query the registry. If the preview is appropriate for your disposable project, the documented apply step writes the project’s RunKit configuration and adoption evidence:
npx --no-install owlrunkit bootstrap --workspace "$PWD" \
--exact owlrunkit@0.24.1 --apply
npx --no-install owlrunkit inspect --workspace "$PWD" --json --compact
For a task that needs to continue across sessions, copy the installed project-definition template, edit it for your actual goal, work item, paths, dependencies and completion conditions, then initialize and inspect it:
cp node_modules/owlrunkit/scripts/runkit-contract/templates/team-project-definition.json \
./project-definition.json
# Edit project-definition.json for your real project before the next command.
npx --no-install owlrunkit project init --workspace . --definition ./project-definition.json
npx --no-install owlrunkit project status --workspace .
project init writes the definition and project state; project status reads the resulting view. To record a first assignment, choose an existing, ready and unassigned work item with no conflicting active paths. Set ASSIGNMENT_ID to a new unique ID, WORK_ITEM_ID to that real work item, and AGENT_ID to the intended executor. With your system clock set correctly, this uses the current UTC time:
npx --no-install owlrunkit project assign --workspace . --assignment-id "$ASSIGNMENT_ID" \
--at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --work-item "$WORK_ITEM_ID" --agent "$AGENT_ID"
npx --no-install owlrunkit project status --workspace .
Assignment writes a project event; it does not start the agent. Record real checkpoints and handoffs as work happens. The Project Driver examples show the command forms; replace their example IDs, timestamps, owners and evidence with the facts of your own project. A successor with access can use project status and project takeover; the latter is a view, not an automatic transfer of ownership.
If the project already has an npm test script whose contents you have inspected and consider safe to run, the README gives this Quick example:
npx --no-install owlrunkit quick-verify --workspace . -- npm test
Quick really runs that script and writes a local receipt and output. The script itself may write files, use the network or have other side effects, so do not run it just because the command is in an example. If it is not suitable, choose another check you understand. A node --version demonstration can show what a receipt looks like, but it does not test your application. We have not run this command for the article or observed a result. Read the README and check the current repository before applying any command.
Where I would start
If you have one task that repeatedly gets lost between sessions, start with its goal, one work item, an owner and a clear next action. If your problem is an untrustworthy green check, start by recording a specific command and the version it actually checked. Add coordination, candidate transfer or stronger verification when the work needs them.
The product descriptions in this article are based on a static reading of the public source at commit 1978a60. The two examples are separate historical records with the limits described above. This introduction does not include a new installation or run of the public package, and it does not constitute a security audit or verification of a new end-to-end business deployment.
What I want from OwlRunKit is for the work to remain understandable when the conversation, the agent or the workspace changes. I hope this introduction makes it easier to see where it can fit into your own workflow.
Repository: https://github.com/yeemio/owlrunkit
Read the series
Starting and coordinating
A five-part handoff for the next agent
How much process does a task need?
What can continue when model quota is unknown?
Different tasks, overlapping write scopes
A recovered project note is not new authorization
Waiting for a file change
When agents keep waking one another
Checking and transferring
Bind a test to the version checked
Choose checks for changed files
Deferred full suite: owner and integration gate
A phone button can exist and still be covered
A test can be blocked before it checks code
Use an entry baseline to understand changes
Transfer uncommitted changes to a clean checkout
A receipt is not all the material needed to verify it
Logs, summaries and sensitive information
Delivery and ongoing work
A remote install disconnected: did it finish?
A rollback report and independently observed recovery
When a completed project's workspace changes
Upgrading a shared skill while projects are active
Measure the trip to a usable result
Earlier Dots–Grokbot example
Introducing the shared task record
The reported handoff cycle