context

The istok context command group provides direct access to durable context stored with the current project.

Context records can represent project knowledge, architectural decisions, instructions, and constraints that should remain available beyond a single task or conversation.

For normal agent workflows, coding agents can read and update project context through MCP. The CLI is useful for inspection, troubleshooting, and direct management.

Commands

Run:

istok context --help

The main context commands are:

All context commands operate on the Istok project associated with the current repository.

Context kinds

Every context record has a kind:

Choosing an appropriate kind helps agents understand how the record should be used.

Add context

Create a record with a title:

istok context add "Authentication architecture" \
  --body "Refresh tokens are rotated after every successful refresh."

Set an explicit kind when the record represents something more specific:

istok context add "Use repository pattern for persistence" \
  --kind decision \
  --body "Application services should not access database adapters directly."

Records can also be tagged:

istok context add "Authentication architecture" \
  --kind note \
  --body "Refresh tokens are rotated after every successful refresh." \
  --tag auth \
  --tag security

--tag can be repeated.

Record metadata

Context records can include additional metadata describing their origin and handling.

Source

The source identifies where the record came from:

user
agent
import

For example:

istok context add "API naming convention" \
  --source user \
  --body "Public API fields use snake_case."

Visibility

Visibility can be:

shared
local_only

Use shared for context intended to participate in the normal project workflow.

Use local_only when the record should remain local to the current Istok environment.

Sensitivity

Sensitivity can be:

normal
private

This metadata lets Istok preserve how a record should be treated alongside its content.

Instructions

An instruction is context that represents guidance for agent work.

For example:

istok context add "Run API tests before completion" \
  --kind instruction \
  --body "Changes to the API must be validated with the API test suite."

Instructions have additional policy fields:

• enabled state;
• priority;
• scope.

Priority

Instruction priority can be:

critical
high
normal
low

For example:

istok context add "Do not modify generated SDK files" \
  --kind instruction \
  --priority high \
  --body "Generated SDK files must be regenerated from the source schema."

Higher-priority instructions are placed before lower-priority instructions when Istok assembles context for agent work.

Scope

Instruction scope is:

project

The instruction applies to work performed in the current Istok project.

List context

List context records:

istok context list

Use this when you want a compact view of the project’s durable context.

Individual records have canonical IDs and revisions that can be used for inspection and mutations.

Show project context

Run show without an ID:

istok context show

This renders the active project context as plain Markdown.

The output is designed to be usable outside the CLI as well. For example, it can be copied into a message, file, or another agent session.

Disabled instructions are excluded from the normal aggregate output.

To include them:

istok context show --include-disabled

Archived records can also be included:

istok context show --deleted

These options can be useful when troubleshooting why a particular instruction or record is not participating in the current project context.

Show one record

Inspect a specific record by its canonical ID:

istok context show RECORD_ID

The detailed view includes the record’s content and metadata, including its current revision.

Use this form before performing a mutation that requires --expected-revision.

Search context

Search the current project’s context:

istok context search "authentication"

Search is useful when the project has accumulated enough durable knowledge that browsing the entire context is no longer convenient.

Coding agents can use context search through MCP as part of their normal workflow.

Update context

Context records use revisions to protect mutations from stale writes.

Inspect the record first:

istok context show RECORD_ID

Then update it with the current revision:

istok context update RECORD_ID \
  --expected-revision REVISION

The update command exposes the editable record fields for the installed version:

istok context update --help

If another operation changes the record first, inspect it again and retry with the latest revision.

Enable an instruction

Enable a previously disabled instruction:

istok context enable RECORD_ID \
  --expected-revision REVISION

Once enabled, the instruction can participate in context assembled for agent work.

Disable an instruction

Temporarily stop an instruction from participating in normal context assembly:

istok context disable RECORD_ID \
  --expected-revision REVISION

Disabling an instruction preserves the record and its history.

It does not need to be deleted just because it is temporarily not applicable.

Disabled instructions are excluded from normal context listing, search, export, and context packages unless explicitly requested through management-oriented operations.

Delete context

Archive a context record using its current revision:

istok context delete RECORD_ID \
  --expected-revision REVISION

The record is preserved as archived state and no longer participates in active project context.

The CLI asks for confirmation where appropriate.

When using JSON mode, provide:

--yes

so the command does not wait for interactive input.

Revisions

update, enable, disable, and delete use compare-and-swap protection through:

--expected-revision REVISION

For example:

istok context disable RECORD_ID \
  --expected-revision 4

If the record has changed since revision 4, the operation fails instead of overwriting the newer state.

Read the record again and use its latest revision.

Context used by agents

Durable context is one source Istok can use when preparing an agent to work on a task.

When a task is claimed, Istok assembles a context package containing applicable project records together with repository retrieval.

Enabled instructions are placed first according to their priority.

Conceptually:

Enabled instructions
        +
Project records
        +
Repository retrieval
        ↓
Context package
        ↓
Task claim
        ↓
Context snapshot
        ↓
Run

The resulting context snapshot is attached to that run.

This means the run keeps the context it started with even if the live project context changes later.

Live context and run snapshots

Project context remains editable while work is in progress.

Suppose a run starts with a particular architectural decision in its context snapshot:

Run A
  └── Context snapshot
       └── Decision revision 3

Later, the live project decision may be updated:

Project context
  └── Decision revision 4

The existing run still retains the snapshot associated with the attempt when it began.

A later run can receive the newer project context.

This keeps execution history inspectable without preventing project knowledge from evolving.

Context and task state

Project context should contain knowledge that remains useful beyond one moment in a task.

Examples include:

• architectural decisions;
• project conventions;
• persistent implementation constraints;
• reusable instructions;
• knowledge that future work should be able to discover.

Active task state belongs with the task instead.

Progress, blockers, dependencies, and current execution state should be recorded in the appropriate task or run rather than duplicated as project context.

JSON output

Context JSON responses use a versioned schema.

Aggregate context output returns a structured list rather than the rendered Markdown used by the default human-readable show command.

Use:

istok context show --json

or other supported context commands with --json when consuming the result programmatically.

See JSON output for the general conventions.

Command help

Use built-in help to inspect the exact options supported by your installed version:

istok context add --help
istok context list --help
istok context show --help
istok context search --help
istok context update --help
istok context enable --help
istok context disable --help
istok context delete --help

Next

Continue with index, search and graph to inspect the repository retrieval capabilities Istok exposes through the CLI.