Quick start

This guide takes you from an existing repository to a coding agent that can use Istok as part of its normal workflow.

Initialize your project

Open the repository you want to use with Istok:

cd my-project

Initialize it:

istok init

Istok registers the repository as a local project and prepares the project state used by coding agents.

You only need to initialize a repository once.

Connect your coding agent

Istok exposes its tools to coding agents through MCP.

The server command is:

istok mcp

When configuring an agent, give it a stable actor ID. Istok uses this identity to associate runs, validation, and other recorded work with the agent that performed it.

For example:

istok mcp --actor-id codex --actor-name "Codex"

--actor-id is the stable identity stored with agent activity. --actor-name provides a human-readable name for that identity.

For personal use, simple IDs such as codex, claude, antigravity, and cursor work well.

If --actor-id is omitted, Istok creates a unique actor identity for that MCP process instead.

Codex

Add Istok as an MCP server:

codex mcp add istok -- \
  istok mcp \
  --actor-id codex \
  --actor-name "Codex"

The global configuration can be used from any repository that you have initialized with Istok.

Claude Code

Add Istok at user scope:

claude mcp add \
  --transport stdio \
  --scope user \
  istok -- \
  istok mcp \
  --actor-id claude \
  --actor-name "Claude Code"

You can inspect configured MCP servers from Claude Code with:

/mcp

Antigravity CLI

Antigravity CLI uses mcp_config.json for MCP servers.

Create or update:

~/.gemini/config/mcp_config.json

Add Istok:

{
  "mcpServers": {
    "istok": {
      "command": "istok",
      "args": [
        "mcp",
        "--actor-id",
        "antigravity",
        "--actor-name",
        "Antigravity CLI"
      ]
    }
  }
}

Start Antigravity CLI as usual:

agy

You can inspect configured MCP servers with:

/mcp

Cursor

Create or update the global MCP configuration:

~/.cursor/mcp.json

Add Istok:

{
  "mcpServers": {
    "istok": {
      "command": "istok",
      "args": [
        "mcp",
        "--actor-id",
        "cursor",
        "--actor-name",
        "Cursor"
      ]
    }
  }
}

With stable actor IDs, work performed through different agents remains attributable in Istok project state.

For example:

Task
 ├── Run by codex
 │    └── validation
 │
 └── Run by claude
      └── validation

Add recommended instructions

Connecting MCP makes Istok available to the agent. Instructions tell the agent when and how to use it as part of its normal development workflow.

For personal use, we recommend adding the Istok workflow to your agent’s global instructions:

• Codex: ~/.codex/AGENTS.md
• Claude Code: ~/.claude/CLAUDE.md
• Antigravity CLI: ~/.gemini/GEMINI.md
• Cursor: User Rules in Cursor settings

Add:

## Working with Istok

Istok is the preferred source of durable project state for non-trivial work in repositories registered with Istok.

Use Istok MCP tools as the primary interface for project state, tasks, context, runs, validation, and repository retrieval.

Do not use the Istok CLI for operations that are available through MCP. If Istok MCP is unavailable or does not expose a required operation, fall back to the CLI when appropriate and prefer structured output.

### Before non-trivial work

Before starting non-trivial work in a repository:

1. Determine the current repository or project root.
2. Resolve the project in Istok by its canonical path.
3. If the project is registered, load its enabled project instructions and relevant durable context.
4. Inspect existing tasks when the requested work may already be represented by one.

If multiple Istok projects could match the current path, use the most specific matching project.

Never silently use a different Istok project.

If the repository is not registered with Istok:

- tell the user;
- do not initialize it automatically;
- continue without Istok unless the user asks to initialize it.

### Tasks

Use an Istok task for work that benefits from durable state, such as feature implementation, bug fixes, refactoring, migrations, investigations, or other non-trivial changes.

Do not create tasks for simple questions, explanations, tiny edits, quick code reading, or lightweight exploratory checks.

For non-trivial work:

1. Reuse an existing relevant task when one exists.
2. Otherwise create a focused task without requiring the user to explicitly ask for one.
3. Use a run to represent the current implementation attempt when appropriate.
4. Record meaningful progress as the work evolves.
5. Record blockers, dependencies, decisions, and reusable context when they become relevant.
6. Validate the result before considering the work complete.
7. Record meaningful validation commands, results, and evidence.
8. Mark the task complete only after the requested result is implemented and sufficiently verified.

If work becomes blocked, keep the task state accurate, record the blocker in Istok, and explain it to the user.

Do not treat implementation alone as completion.

### Project instructions and context

Enabled project instructions returned by Istok are required project context. Load and follow them during non-trivial work.

Use Istok context for durable knowledge that should survive the current conversation, such as important decisions, constraints, investigation results, blockers, handoff information, and other reusable project knowledge.

Do not use durable context as a transcript of the conversation.

Do not duplicate active Istok task state into temporary TODO files, plans, or status documents unless the user explicitly requests an export or document.

### Repository retrieval

Prefer Istok search, index, and graph capabilities for repository retrieval when they are useful.

Use retrieved results to locate relevant code and context, but verify exact implementation details against the current source before making changes.

If Istok retrieval is insufficient, inspect the repository directly.

### Validation and completion

Before marking non-trivial work complete:

- verify the relevant acceptance criteria;
- run appropriate tests, builds, linters, type checks, or other validation;
- record meaningful validation evidence in Istok;
- ensure task, run, progress, and blocker state reflect the actual result.

Do not claim that validation passed unless it was actually performed successfully.

If some validation cannot be performed, keep that limitation explicit instead of presenting the work as fully verified.

Do not make the user manually maintain Istok state during normal work. Keep Istok synchronized with the work you perform.

With these instructions, Istok becomes part of the agent’s normal workflow whenever it works inside a registered repository.

The agent can decide when work is substantial enough to benefit from durable state, create or reuse the appropriate task, preserve useful context, track implementation attempts, and record validation without requiring you to manage Istok manually.

Start working

Setup is complete.

Continue talking to your coding agent normally.

You do not need to manually create tasks, start runs, prepare context, record progress, or manage validation.

For example, instead of saying:

Create an Istok task for the authentication timeout, investigate it, record your progress, validate the fix, and close the task.

you can simply say:

Investigate why authentication requests sometimes time out and fix the problem.

For non-trivial work, the agent can use Istok to:

1. resolve the current project;
2. load its project instructions and relevant durable context;
3. find an existing relevant task or create one;
4. use a run for the current implementation attempt;
5. retrieve relevant repository context;
6. record meaningful progress, decisions, dependencies, and blockers;
7. validate the result and preserve useful evidence;
8. leave accurate durable project state that another session or agent can inspect later.

For simple questions, code reading, tiny edits, and small consultations, the agent can respond directly without creating unnecessary project state.

Istok runs underneath the workflow rather than replacing your normal interaction with the coding agent.

Use project instructions for stricter workflows

Global instructions are the recommended personal default.

For repositories where Istok should be an explicit part of the shared development workflow, you can also commit project-level instructions.

Use:

• Codex: AGENTS.md
• Claude Code: CLAUDE.md
• Antigravity CLI: AGENTS.md
• Cursor: AGENTS.md

AGENTS.md can therefore be shared by Codex, Antigravity CLI, and Cursor. If the repository also uses Claude Code, add the corresponding Istok instructions to CLAUDE.md.

Project instructions can be committed with the repository so developers and coding agents use the same workflow.

Add:

## Working with Istok

This repository uses Istok as the source of truth for durable task state, project context, implementation runs, progress, blockers, and validation evidence.

For non-trivial work:

1. Resolve this repository as an Istok project.
2. Load its enabled project instructions and relevant context.
3. Reuse an existing relevant task, or create one when no suitable task exists.
4. Use a run for the current implementation attempt when appropriate.
5. Keep meaningful progress, decisions, dependencies, and blockers in Istok.
6. Validate the result and record meaningful evidence.
7. Mark the task complete only after the requested work is implemented and sufficiently verified.

Prefer Istok MCP tools over the CLI when MCP is available.

Do not create Istok tasks for trivial questions or tiny edits.

Do not duplicate active Istok task state into local TODO files, plans, or status documents.

If this repository is not registered with Istok, stop the Istok workflow and tell the user. Do not initialize another project or silently use a different Istok project.

You normally do not need to duplicate the complete global Istok workflow in every repository.

The global instructions define how the agent works with Istok.

Project-level instructions are useful when a repository needs to explicitly require Istok, share the workflow with other contributors, or add stricter repository-specific rules.

Continue in another session

Istok state belongs to the project rather than to a particular conversation.

When you start a new session, the agent can inspect existing tasks, context, runs, progress, blockers, and validation state instead of relying only on previous chat history.

Because each configured agent has a stable actor identity, the project history can also preserve which agent performed each attempt.

Work can therefore move between sessions or agents without requiring them to share conversation history.

For example:

Session A
   │
   │ task + run + progress
   ▼
 Istok project state
   │
   │ context + validation
   ▼
Session B

The same applies when changing agents:

Codex
   │
   │ implementation attempt
   ▼
Istok
   │
   │ durable project state
   ▼
Claude Code

The next agent can inspect what has already happened, understand the current task state, and continue from durable project context instead of reconstructing the work from the previous conversation.

You continue working with the agent as usual; Istok provides the durable state underneath that workflow.

Next

Continue with Projects to learn how Istok organizes project state.