
istok
io.github.vtimame/istok
Local task tracker for coding agents that runs their checks and keeps the proof behind done.
Documentation
Istok
One workspace for every coding agent.
Website · Quick start · Документация на русском · Releases
Your coding agent says "done". Istok keeps the proof: the task, every attempt, and the checks behind the result, with Istok running the commands itself. It all stays with your project instead of inside one conversation, so a new session — or a different agent, or another of your machines — picks up where the last one stopped.
A bug fix Claude Code made in a sample project. It could not run the tests, said so and left the task open; then Istok ran go build and go test itself, and the task closed.
Why
If you work with Claude Code, Codex or Cursor, three things keep getting in the way:
- Sessions end. Close the chat or hit the context limit, and the plan, the decisions and the half-finished work go with it.
- Work is invisible. With several agents in several repositories, it is hard to tell who did what and what quietly stalled.
- "Done" is a claim. The agent says the tests pass; nothing shows that it ran them.
Istok is a local CLI and MCP server. Your agent records its work through MCP while it goes; you keep talking to it as before. Everything stays on your machine in one SQLite file: no account, no cloud, and nothing written into your repository. To work on several machines, run your own sync hub.
Quick start
With Claude Code, install the plugin. It brings the MCP server and the hooks, and downloads Istok on first use when it is not installed yet:
/plugin install istok --marketplace vtimame/istok.sh
Then go to step 3. To use istok in your own terminal too, install it as in step 1.
1. Install (Linux and macOS, no root needed):
curl -fsSL https://get.istok.sh | sh
Or with Homebrew: brew install vtimame/tap/istok.
2. Connect your agent once, for your user. For Claude Code without the plugin:
claude mcp add --transport stdio --scope user istok -- \
istok mcp --actor-id claude --actor-name "Claude Code"
For Codex:
codex mcp add istok -- \
istok mcp --actor-id codex --actor-name "Codex"
To keep work across restarts and compactions, add the hooks once:
istok hooks install claude # or: istok hooks install codex
The server lists the core workflow tools; start it with istok mcp --tools full for every tool.
Cursor and other MCP clients are covered in the quick start, together with a short block of instructions that tells the agent when to use Istok.
3. Ask the agent to register your project. Start it in the repository and say:
Register this project in Istok.
Then give it real work as usual. It creates a task, claims it, runs the checks through Istok and completes the task with that evidence.
4. See what happened:
istok task list
istok task show 1
Each task shows its history, with every run and the linked commits.
Learn more
- What is Istok — the problem and what you get.
- Working with your agent — what to say to continue work, remember a rule or hand over to another agent.
- Sync between devices — run a hub and continue the same project on another machine.
- How Istok works — projects, tasks and runs, validation, context and knowledge.
- CLI and MCP tools reference.
- FAQ and troubleshooting.
The documentation is also available in Russian, and as llms.txt for agents.
Sync between your devices
To continue the same project on another machine, run a sync hub on any server your devices reach — a VPS or a home server, no domain or certificate needed. The hub stores only rows encrypted on your devices. With Docker, take docker/hub/compose.yml:
ISTOK_HUB_ADVERTISE=203.0.113.10:7443 docker compose up -d
docker compose exec hub istok hub device add laptop # prints a one-time invitation
To reach the hub from several networks, list its addresses separated by commas, for example a LAN and a Tailscale address; devices use whichever answers.
On the device, istok sync join CODE registers it and istok sync enable in a project folder starts syncing; the second device joins with --key from istok sync key, and istok sync enable in its clone of the repository fetches the same project. The image ghcr.io/vtimame/istok-hub is published with every release for x86-64 and ARM64.
Platforms
Releases are built for Linux (x86-64, ARM64) and macOS (Intel, Apple Silicon). Windows is not supported yet.
Releases are signed. istok update checks for a newer stable release, verifies it, backs up the database and migrates it; istok update --check only reports. A Homebrew install is updated with brew upgrade istok.
Build from source
Istok is written in Go. Building needs Go with cgo (for SQLite):
make build # writes bin/istok
make install # installs into ~/.local/bin
go test ./...
A source build cannot update itself; install an official release for istok update.
License
Apache 2.0. Changes are listed in the changelog.
istok-clinpm install istok-cli