istok

Projects

Learn how Istok scopes durable agent state to a repository.

A project is the boundary around the durable state Istok keeps for a repository.

When you run:

istok init

Istok registers the current repository as a project. From that point, coding agents connected through MCP can identify the project they are working in and access its Istok state.

Project-scoped state

Istok keeps work associated with the project rather than with a particular conversation or coding agent.

A project can contain:

  • tasks and their dependencies;
  • project context and persistent knowledge;
  • progress recorded while work is in progress;
  • runs representing attempts to complete tasks;
  • validation results and other execution evidence.

This gives agents a shared place to inspect what is happening in the repository.

Repository identity

Istok identifies the project from the repository an agent is working in.

This means a globally configured istok mcp connection can be reused across multiple repositories. The agent does not need a separate MCP server configuration for every project.

Only repositories that you explicitly initialize with Istok become Istok projects.

One project, multiple sessions

Project state is independent of an individual agent session.

For example, you might ask an agent to begin implementing a feature today and continue the work in a new session tomorrow.

The new session can inspect the same project and recover the relevant Istok state instead of relying only on the previous conversation.

The same applies when different coding agents work with the repository.

Project context

A project can also contain durable information that should remain available beyond a single task.

This is useful for knowledge such as:

  • architectural decisions;
  • important repository conventions;
  • constraints that agents should remember;
  • implementation notes that remain relevant to future work.

Task-specific information can stay with the task, while longer-lived knowledge remains available at the project level.

Inspecting a project

Most project operations happen through the coding agent, but the CLI can also be used to inspect registered projects when needed.

For example:

istok project list

and:

istok project show

The full command surface is documented in the CLI reference.

Next

Continue with Tasks to see how Istok represents durable units of work inside a project.