Do I need to create tasks manually?
No.
In the normal workflow, you continue talking to your coding agent as usual. For non-trivial work, an agent configured to use Istok can find an existing task or create one when needed.
The CLI remains available for inspection, troubleshooting, scripting, and direct control.
Does every request need a task?
No.
Tasks are useful when durable work state matters: implementation, debugging, refactoring, multi-step investigations, or work that may continue across sessions.
Simple questions, code reading, small consultations, and other lightweight interactions usually do not need a task.
Do I need to tell the agent to use Istok every time?
Usually not.
Once MCP is configured and your agent instructions describe the Istok workflow, the agent can use Istok automatically for non-trivial work in initialized repositories.
See the Quick start for the recommended setup.
Can I configure Istok globally?
Yes.
You can configure the Istok MCP server globally in your coding agent and use that configuration across repositories initialized with Istok.
Each repository still needs to be initialized once with:
istok initAgent instructions can also be global, project-specific, or a combination of both.
Why should I configure an actor ID for each agent?
A stable actor ID lets Istok attribute recorded work to the agent that performed it across MCP restarts.
For example, you can configure Codex with --actor-id codex and Claude Code with --actor-id claude. Runs and related work can then remain associated with those actor identities.
--actor-name provides a human-readable name for the identity.
If no actor ID is configured, Istok creates a unique identity for that MCP process instead.
Will an agent initialize repositories automatically?
That depends on your agent instructions.
The recommended global instructions tell the agent to use Istok when the current repository is already registered, but not to initialize arbitrary repositories without permission.
For repositories where Istok is required, you can commit stricter project instructions alongside the code.
Can I use Istok with multiple coding agents?
Yes.
Istok project state is not tied to one coding agent. One agent can begin work and another can later inspect the same tasks, context, runs, and validation history.
Stable actor IDs also make it possible to distinguish which agent performed a particular attempt.
See Handoffs for the underlying model.
What happens when I start a new agent session?
The conversation starts fresh, but Istok project state remains available.
The agent can inspect existing tasks, project context, progress, runs, and validation results before continuing. The previous chat does not need to be reproduced.
What is the difference between agent instructions and Istok context?
Agent instruction files such as AGENTS.md or CLAUDE.md tell the coding agent how it should work — for example, when to use Istok and when to create or claim a task.
Istok project context stores durable knowledge about the project — for example, architectural decisions, constraints, conventions, reusable instructions, and notes.
Agent instructions
↓
How the agent should work
Istok project context
↓
What the project should rememberDo I need to manage the repository index manually?
Normally, no.
Istok checks index freshness automatically when repository retrieval is needed, including search, graph reads, and normal task claim.
istok index status is useful for inspection, while istok index rebuild is primarily a repair or diagnostic operation.
What happens if validation fails?
The task does not need to be recreated.
The failed validation remains part of the run history. The agent can continue the implementation and validate again after addressing the problem.
What happens if an agent session stops during a task?
The task and any recorded Istok state remain with the project.
If an active run needs to continue, its actor can recover it when appropriate. Otherwise, the task can be worked through another attempt while the previous run remains part of the history.
See Runs and validation.
Why does Istok have both tasks and runs?
A task represents what needs to be done. A run represents one attempt to do it.
A task can therefore survive interrupted or failed attempts while each run preserves the history of that particular attempt.
See Runs and validation for the full model.
Do I need to understand leases and revisions?
Not for normal agent-driven use.
Leases and revisions become relevant when you operate Istok directly through the CLI, troubleshoot interrupted work, or build an integration against its lower-level contracts.
See the task and run references when you need those details.
What are MCP profiles?
Profiles control which Istok MCP capabilities are exposed to an agent.
The standard setup does not require choosing one. Profiles are an advanced configuration for cases where you intentionally want a different capability surface.
See MCP.
Can I use Istok directly from the CLI?
Yes.
The CLI exposes the same project workflow for inspection, troubleshooting, scripting, automation, and direct control.
For normal coding work, you can let the agent perform the workflow through MCP instead.
Start with the CLI overview.
Where does Istok keep project state?
Istok stores durable project state locally. Repository retrieval indexes and managed artifacts are stored separately from the main project-state database.
Most users do not need to manage these paths directly.
See Configuration when you need to inspect or customize storage locations.
What should I do if Istok MCP is unavailable?
First verify that Istok itself is available:
istok versionThen check the MCP configuration used by your coding agent.
If the agent cannot access Istok, it should report the problem rather than guessing or inventing project state.
See Troubleshooting for common setup problems.