Repository avatar
Other Tools
v0.5.7
active

istok

io.github.vtimame/istok

Local task tracker for coding agents that runs their checks and keeps the proof behind done.

Documentation

Istok

Istok

One workspace for every coding agent.

Website · Quick start · Документация на русском · Releases

Release Apache 2.0 Documentation

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.

istok task show: a task Claude Code finished, with go build and go test run by Istok

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

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.

NPM
istok-cli
Install Command
npm install istok-cli
Runtime: npx