Okto Pulse

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

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:

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:

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.

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.

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:

• 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

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

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

okto-pulse serve

python scripts/smoke_embedding.py

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

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.

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