okto-pulse 0.3.0

Okto Pulse — spec-driven project management with AI agents via MCP. Local-first, single command setup.

Okto Pulse

Spec-driven project management for AI-assisted development.

Okto Pulse turns ideas, refinements, specs, tasks, tests and bugs into a governed SDLC board that AI agents can operate through MCP.

Ship with AI. Stay in control.

---

Table of Contents

• What is Okto Pulse?
• Platform Surface
• Get Started
• Connect an AI Coding Agent
• Token Usage
• Core Workflow
• Governance Gates
• Knowledge Graph
• Architecture
• CLI Reference
• Run with Docker
• Data Storage
• From Source
• Troubleshooting
• Release Notes
• License

Reference documents

Document	Contents
docs/ARCHITECTURE.md	Dependency owner matrix, adapter source map and the port → adapter matrix
docs/RELEASE-NOTES.md	Full changeset per version
docs/TOKEN-USAGE.md	Measured MCP context cost for agents
docs/kg-health.md	Knowledge Graph health signals and triage

What is Okto Pulse?

Okto Pulse is a local-first SDLC workbench built for teams that use AI coding agents but still want traceability, quality gates and durable project memory.

Instead of sending an agent straight from a prompt to code, Okto Pulse keeps the work explicit:

Stories -> Ideation -> Refinement -> Spec -> Sprint -> Tasks / Tests / Bugs

Every stage has structured artifacts, lineage, status transitions and validation rules. Agents can create and update those artifacts through MCP tools, while humans can inspect and steer the same work in the web UI.

Platform Surface

Current 0.3.0 surface:

Surface	Count
Governance gates	17
Core MCP tools	281
Community-only MCP tools	0
MCP tools exposed by okto-pulse serve	281

The community package materializes the full okto-pulse-core command catalog in its FastMCP host. That means installed community runtimes expose the complete core tool catalog while keeping the CLI, frontend and packaging layer separate from the core engine. The MCP count is measured from the transport-neutral Core catalog at implementation time; Community adds operational resources and adapters, not extra community-only MCP tools.

Get Started

1. Install

pip install okto-pulse

Okto Pulse requires Python 3.11+.

[!NOTE] On first run, Okto Pulse downloads the all-MiniLM-L6-v2 sentence-transformers model into the Hugging Face cache. This powers semantic search in the Knowledge Graph. If the model cannot be downloaded, the app still starts in deterministic stub mode and the Settings view reports that semantic search is disabled.

2. Initialize a workspace

Run this inside the project directory where your coding agent will work:

okto-pulse init

This creates:

• the local data directory under ~/.okto-pulse/
• a default board and agent
• a project-local .mcp.json that points your agent at the local MCP server

3. Start the app

okto-pulse serve

Default endpoints:

Endpoint	URL
Web UI + API	http://localhost:8100
MCP server	http://localhost:8101/mcp

Both listeners run in one Python process. This keeps the embedded graph database under a single writer while still exposing independent API/UI and MCP ports.

4. Open the UI

Go to http://localhost:8100, select the default board and start with either:

• a Story, when you want lightweight pre-ideation context grouped by topic
• an Ideation, when the feature or problem is already ready to be discussed

Connect an AI Coding Agent

Most agent tools can discover the generated .mcp.json automatically when they run from the same directory.

Agent or tool	Setup
Claude Code	Run it from the directory that contains .mcp.json.
Claude Desktop	Copy the generated MCP server block into Claude Desktop settings.
Cursor	Add the MCP server URL in Cursor MCP settings.
VS Code	Copy the server block into .vscode/mcp.json.
Windsurf / Cline	Use the generated .mcp.json when supported.

Generated shape:

{
  "mcpServers": {
    "okto-pulse": {
      "url": "http://localhost:8101/mcp?api_key=dash_..."
    }
  }
}

If you change the MCP port, regenerate the file:

okto-pulse init --agents

Token Usage

Connecting an agent over MCP has a fixed context cost (the tool catalogue) plus a variable cost (tool responses). Response projections — summary, detail, full — let you trade detail for tokens.

→ Measured token usage — fixed cost per connection, on-demand resources, variable response cost and ballpark session profiles.

Core Workflow

Okto Pulse is intentionally workflow-first. Each stage answers a different question.

Stage	Purpose
Stories	Optional lightweight user-story inputs, grouped by topic, that can feed one or more ideations.
Ideation	Capture the problem, assess ambiguity and collect Q&A before committing to a solution path.
Refinement	Investigate code, constraints, prior decisions, mockups, architecture and knowledge entries.
Spec	Define acceptance criteria, functional requirements, business rules, API contracts, tests and decisions.
Sprint	Slice approved specs into reviewable implementation batches when the work is large.
Tasks / Tests / Bugs	Execute implementation with linked tests, bug evidence, validation and conclusions.

The lineage graph keeps these relationships inspectable, including story-to-ideation and task-to-test/bug relationships.

Governance Gates

Okto Pulse protects the workflow with checks that run on status transitions.

The platform currently has 17 named governance gates:

Gate family	Gates
Resource readiness	Resource readiness; resource-to-task coverage
Spec coverage	Scenario/test coverage; functional requirement/business rule coverage; technical requirement/task coverage; API contract/task coverage; active decision/task coverage
Validation and evaluation	Spec validation; spec qualitative evaluation; task validation
Execution quality	Task start/spec readiness; task conclusion; cognitive closeout; architecture-findings done; test evidence; bug test-first/traceability
Sprint health	Sprint closure/evaluation

• Specs require coverage across acceptance criteria, functional requirements, business rules, API contracts, decisions and test scenarios.
• Tasks cannot start until the parent spec has the required scenario coverage.
• Tasks moving to done require a structured conclusion with completeness and drift assessment.
• Done transitions are also held while unresolved cognitive-consolidation items remain (cognitive closeout), and active architecture warnings block a spec or card from reaching done (architecture-findings gate). Both moved from defined to enforced in 0.2.3.
• Test cards require evidence before they can be marked as automated, passed or failed.
• Bug cards follow a test-first workflow and must remain traceable to the task and related test work.
• Validation gates can require independent review before specs or tasks are considered complete.

Board settings let teams tune thresholds without removing the traceability model.

Knowledge Graph

Okto Pulse maintains an embedded per-board Knowledge Graph for durable project memory.

Agents use the graph to:

• find related prior decisions
• detect contradictions and superseded context
• reuse lessons from previous bugs
• query global discovery context across boards
• consolidate specs, bugs and implementation conclusions into searchable knowledge

Operational health is visible through:

• the in-product KG view
• MCP health tools
• dead-letter and queue metrics
• graph database runtime settings in the board settings panel

GET /health is a constant-time liveness endpoint: it performs no storage scan and keeps the backward-compatible HTTP 200 and status: "healthy" contract while the process can answer requests. Relational integrity is available on the explicit, read-only GET /health/integrity diagnostic through integrity_status and findings.sprint_origin_integrity; do not use that storage-backed route as a recurring liveness probe. A missing sprint lineage foreign key with clean data is degraded; an invalid lineage row or a probe failure is critical. Direct SQL repair is unsupported; use application workflows or a verified backup/restore procedure.

Architecture

Okto Pulse ships as two packages: okto-pulse-core owns the SDLC domain, the governance gates and the Knowledge Graph contracts as pure Protocol seams; okto-pulse (this package) owns every concrete mechanism — SQLite, Kùzu/LadybugDB, the filesystem, the scheduler, telemetry state, the REST app and the MCP host.

Core never imports Community. Community fills the ports at startup, and an unfilled slot fails closed rather than falling back to a silent default.

→ Architecture in full — dependency owner matrix (AF-05/AF40), registration flow, the adapter source map, and the port → adapter matrix showing which core contract each of the 115 adapter modules implements.

CLI Reference

Command	Description
okto-pulse init	Initialize local data, seed the default board and generate .mcp.json.
okto-pulse init --agents	Regenerate MCP agent configuration.
okto-pulse init --accept-terms	Accept terms non-interactively. Also supported through OKTO_PULSE_TERMS_ACCEPTED=1.
okto-pulse serve	Start API/UI and MCP in one Python process.
okto-pulse serve --api-port N --mcp-port M	Override API/UI and MCP ports.
okto-pulse status	Show service status, database path, size and board counts.
okto-pulse reset [-y]	Delete local data and re-seed after confirmation.
okto-pulse kg dedup-entities <board_id>	Run the idempotent KG entity deduplication migration for a board.
okto-pulse kg migrate-schema [--all-boards]	Apply graph schema migrations manually. The runtime also auto-heals supported legacy schemas.

Run with Docker

Published image

docker run -d --name okto-pulse \
  -e HOST=0.0.0.0 \
  -e MCP_HOST=0.0.0.0 \
  -p 8100:8100 \
  -p 8101:8101 \
  -v okto-pulse-data:/data \
  ghcr.io/oktolabsai/okto-pulse:latest

Then open http://localhost:8100 and retrieve the bootstrap API key:

docker exec okto-pulse okto-pulse api-key

Compose

Use the production compose file when you want a PyPI-based image:

docker compose -f docker-compose.prod.yml build
docker compose -f docker-compose.prod.yml up -d

Use the local compose file when hacking on the community package together with a sibling okto-pulse-core checkout:

docker compose build
docker compose up -d

Environment variables

Variable	Default	Purpose
HOST	127.0.0.1	API/UI bind host. Use 0.0.0.0 in containers.
MCP_HOST	127.0.0.1	MCP bind host. Use 0.0.0.0 in containers.
DATA_DIR	~/.okto-pulse	SQLite database, uploads and graph storage root.
KG_BASE_DIR	derived from DATA_DIR	Per-board graph database location.
HF_HOME	~/.cache/huggingface	Sentence-transformers model cache.
MCP_TRACE_ENABLED	unset	Set to 1 to record MCP calls for replay testing.
MCP_TRACE_DIR	${KG_BASE_DIR}/mcp_traces	Trace output directory when tracing is enabled; falls back to ./mcp_traces when KG_BASE_DIR is unset.

Data Storage

All default local state lives under ~/.okto-pulse/:

~/.okto-pulse/
|-- data/
|   `-- pulse.db
|-- boards/
|   `-- {board-id}/
|       `-- graph.lbug
|-- global/
|   `-- discovery.lbug
|-- uploads/
|   `-- {board-id}/
`-- mcp_traces/

[!WARNING] Do not delete graph database directories to "fix" graph errors. Use the KG migration and health tools so schema or runtime issues remain diagnosable.

From Source

Clone both repositories next to each other:

git clone https://github.com/OktoLabsAI/okto-pulse-core.git
git clone https://github.com/OktoLabsAI/okto-pulse.git
cd okto-pulse

Install both packages in editable mode:

pip install -e ../okto-pulse-core -e .
okto-pulse init
okto-pulse serve

Build the frontend before packaging:

cd frontend
npm install
npm run build
cd ..

Troubleshooting

Embedding model did not download

Restore network access and restart:

okto-pulse serve

You can also smoke-test the embedder from a source checkout:

python scripts/smoke_embedding.py

AI agent cannot connect to MCP

Check that the MCP port in .mcp.json matches the running server:

okto-pulse serve --api-port 8100 --mcp-port 8101
okto-pulse init --agents

If running in Docker, expose the MCP listener with MCP_HOST=0.0.0.0 and publish the port.

Graph database reports lock, WAL or size errors

First confirm that only one okto-pulse serve process is using the same data directory. Then open board settings and check:

• Graph DB buffer pool size
• Graph DB max database size per board
• KG health and dead-letter metrics

Use the contextual error message as the source of truth when reporting an issue.

Release Notes

Current: 0.3.0 — Community absorbed every concrete adapter the core shed during its hexagonal decontamination, and became the sole owner of mechanism. 63 commits over v0.2.6.

→ Full release notes — 0.3.0 changeset in detail, plus 0.2.6, 0.2.5, 0.2.3, 0.2.2, 0.2.1 and 0.2.0.

SaaS Closure Audit

The executable ownership matrix is generated by okto-pulse-saas-closure. Every transitional budget must remain zero; the command fails closed on import, dependency, adapter, wheel, or documentation drift.

Surface	Core contract	Community/local adapter	SaaS swap target	Executable gates
Relational runtime	repository/UoW and schema lifecycle ports; no ad-hoc dialect or engine/session factory bypass	SQLite/SQLAlchemy adapters in community.adapters.sqlalchemy_* and relational_schema_lifecycle	SQLite -> Aurora/Postgres	run_relational_residue_gate, audit_dependency_conformance, audit_community_core_import_boundary
KG graph runtime	KG interfaces, policies and adapter-neutral schema compatibility helpers	LadybugDB/Kuzu adapters in community.adapters.kuzu_* and global_discovery_runtime	LadybugDB/Kuzu -> Neptune	audit_dependency_conformance, ImportBoundaryGate, audit_community_core_import_boundary
Durable files and artifacts	StorageProvider, RebuildAuditArtifactStore and CognitivePendingWorkProvider contracts	filesystem storage, upload_dir, rebuild audit storage and cognitive-pending providers	filesystem -> S3	run_rebuild_audit_storage_gate, run_core_settings_defaults_gate, run_public_config_stability_gate
Telemetry effects	TelemetryPort contracts, event schema and privacy policy	local JSONL store, state files, beacon sender and product telemetry adapters	local telemetry files/API -> AWS telemetry API	run_telemetry_store_ownership_gate, run_telemetry_sender_ownership_gate, run_telemetry_product_ownership_gate
Scheduler/runtime effects	JobSpec, SchedulerControl and KG daily tick policy	APScheduler-backed SingletonSchedulerControl	APScheduler local runtime -> runtime scheduler adapter	SchedulerControlSymbolGate, scheduler_signal_conformance
MCP resources and versions	MCP instruction/resource/version provider ports and stable public catalog	Community resource catalog, capability descriptors and package version wiring	local catalog/version reads -> deployment provider	run_public_config_stability_gate, register_instruction_provider, register_package_version_provider

F16 executable surface	Owner	Observed	Terminal target
Core import rows	Core	5345	classified
Community-to-Core import rows	Community	725	classified
Direct dependency rows	Distribution owner	23	classified
import_boundary_baseline budget	675c43ee-7d91-4cc3-8f87-44eeb293f90c	0	0
singleton_baseline budget	675c43ee-7d91-4cc3-8f87-44eeb293f90c	0	0
dependency_temporary_exceptions budget	675c43ee-7d91-4cc3-8f87-44eeb293f90c	0	0
graph_runtime_compatibility budget	675c43ee-7d91-4cc3-8f87-44eeb293f90c	0	0
rebuild_artifact_compatibility budget	675c43ee-7d91-4cc3-8f87-44eeb293f90c	0	0
community_private_reach_ins budget	675c43ee-7d91-4cc3-8f87-44eeb293f90c	0	0
community_adapter_bridges budget	675c43ee-7d91-4cc3-8f87-44eeb293f90c	0	0
af35_relational_residue budget	675c43ee-7d91-4cc3-8f87-44eeb293f90c	0	0

License

Elastic License 2.0 - free for personal and commercial use. You may not provide this software to third parties as a hosted or managed service.

Copyright 2026 Okto Labs