TaskState Vault is a local-first task-state and project-governance toolkit for coding agents working on complex or long-running projects.

It stores project intent, task graphs, execution queues, task-local state, evidence, artifacts, errors, and reusable account or domain information in a filesystem and SQLite-backed workspace.

TaskState Vault:
  The overall project and user-facing tool.

ContextKernel:
  Execution-mode routing, Project Governor, task graph, execution queue,
  objective changes, run state, and context loading.

TaskFS:
  The on-disk state layout under .taskstate-vault.

TaskDB:
  SQLite indexes for account, domain, project, task, pointer, import-copy,
  and project-file search records.

Clone the repository, then install it in editable mode:

git clone <your-fork-or-repo-url> taskstate-vault
cd taskstate-vault
python -m pip install -e .

You can also run it without installing:

python -m taskstate_vault.cli.main --help

Use the cloned repository path as the central TaskState Vault root:

cd <TASKSTATE_VAULT_REPO>
tsv --root <TASKSTATE_VAULT_REPO> init
tsv --root <TASKSTATE_VAULT_REPO> project create --title "My Complex Project" --mode complex_project --project-id project_demo --workspace <PROJECT_WORKSPACE>
tsv --root <TASKSTATE_VAULT_REPO> governor next --project project_demo
tsv --root <TASKSTATE_VAULT_REPO> task create --project project_demo --queue-rank 1
tsv --root <TASKSTATE_VAULT_REPO> workspace init-task --workspace <PROJECT_WORKSPACE> --project project_demo --task <TASK_ID>
tsv --root <TASKSTATE_VAULT_REPO> index project-files --project project_demo --path <PROJECT_WORKSPACE>
tsv --root <TASKSTATE_VAULT_REPO> context build --project project_demo --task <TASK_ID>

Installed script names:

tsv
taskstate-vault

Start the local operations console:

tsv --root <TASKSTATE_VAULT_REPO> ui serve

The UI opens at http://127.0.0.1:8765/ by default. It provides a local-first project operations console with project grouping, task DAG visualization, execution queue management, records, state-file editing, hidden items, archive management, and Chinese/English language switching.

The default local administrator is admin with password 12345678. Change this password from the Settings page before using the console with real project data.

Python SDK:

from taskstate_vault import TaskStateVault

vault = TaskStateVault("<TASKSTATE_VAULT_REPO>")
vault.init()
project = vault.contextkernel.create_project("My Complex Project", execution_mode="complex_project", project_id="project_demo")
task = vault.contextkernel.create_task_from_queue(project["project_id"])
context = vault.contextkernel.build_context(project["project_id"], task["task_id"])

MCP-ready adapter:

tsv --root <TASKSTATE_VAULT_REPO> mcp tools

TaskState Vault is most useful when Codex is told where to find its startup guide.

1. Clone this repository.
2. Replace <TASKSTATE_VAULT_REPO> in docs/CODEX_CUSTOM_INSTRUCTIONS_DRAFT.md with the absolute path to your clone.
3. Put the resulting text in Codex custom instructions.
4. Keep docs/CODEX_USAGE_GUIDE.md in the repository so Codex can read the operational protocol at task start.

taskstate_vault/
  Public Python package, CLI, TaskFS, ContextKernel, TaskDB, MCP adapter, and UI implementation.

docs/
  Usage guide, custom-instruction template, structure reference, and initial guidance.

tests/
  End-to-end flow tests using temporary TaskFS roots.

pyproject.toml
  Package metadata and CLI entry points.

Runtime state is created under .taskstate-vault/ and is intentionally ignored by git.

• Execution modes: simple_task, managed_task, complex_project, program_scale
• Project Governor
• Project intent and project model files
• Task graph and execution queue scheduling
• Account/domain/project/task layered indexes
• tsv:// pointer URIs
• Task-level copies of relevant long-term information
• Task state and next action files
• Run start/record/finish
• Evidence, artifacts, errors, and object records
• Project file indexing
• Context build/explain
• Local React-based operations console
• Public Python SDK facades: TaskStateVault, TaskFS, TaskDB, ContextKernel
• MCP-ready JSON-callable adapter and tool metadata
• Objective change log
• Promotion candidates
• Final audit and initial guidance generation

python -B -m unittest discover -s tests -v

• Codex usage guide
• Product guide / ????
• Custom instructions draft
• Project structure
• Packaging model
• Initial guidance

MIT. See LICENSE.