Okto Pulse

Okto Pulse

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 -> 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.4.0 implementation 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.

Community keeps its local REST identity deliberately human-only. Authenticated agent submissions use the Core MCP surface locally; a SaaS edition may inject an agent-aware AuthenticationPort into the same edition-neutral REST contract. Neither path makes Community acquire, clone, browse, probe or inspect source code: the external agent checks access and capabilities in its own environment and submits only the bounded result.

The Codex (CLI) button copies codex mcp add okto-pulse --url "<Pulse MCP URL with agent key>", using the runtime MCP address and the newly revealed API key. Install Codex CLI first. After rotating the key, copy and run the new command, then restart the Codex session; the old key stops working. Configuration copying is disabled when the reveal-once key is hidden. Keep the copied command private: it contains the key and can be saved in shell history and Codex's configuration. The command configures a connection; board access still needs to be granted in Pulse. See the official Codex MCP documentation.

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 returns HTTP 200 with status "healthy" while the process can answer requests. Use application workflows or a verified backup/restore procedure for recovery; direct SQL repair is unsupported.

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, Okto Grafx, 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 adapter module implements.

CLI Reference

The former reset, verify-pipeline and kg command group are no longer accepted, including their help/options. The CLI returns the standard unknown-command error (exit 2) before accessing data. Use status for local observation; it does not certify KG health or perform recovery. See health observations and the historical CLI corrections.

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. The first startup prints the newly created bootstrap API key once. Persisted keys cannot be recovered; regenerate a key through the UI/API if needed. Automation can use init --bootstrap-key-handoff and consume that explicit file with api-key --handoff-file.

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

For Grafx, generation is the Pulse default. Pulse owns each managed generation directory and performs restore/generation replacement only with its handles closed, satisfying this policy's closed lifecycle. It amortizes descriptor identity proofs only for Grafx's canonical heap, catalog, index and WAL names; control and unknown names remain strict. This removes repeated namespace system calls from page-heavy graph reads without changing Grafx locking, WAL, OCC or snapshot rules. Keep it for the ordinary local Pulse runtime where no other tool mutates the live generation.

strict proves the physical identity behind every cached descriptor hit. Select it when external tools may touch the database directory, during manual maintenance or forensics with uncertain directory provenance, on mixed-trust hosts, with live file replacement/replication that swaps names, or on an unsupported shared filesystem. Its advantage is detecting an out-of-protocol path replacement at the next physical operation; its cost is repeated namespace/descriptor calls on hot files. Conversely, generation can defer detection of that unsupported mutation until directed invalidation, generation advance or reopen. The policy is process-local and not persisted; it does not alter OCC, WAL, durability or multiwriter/multireader guarantees. Pulse fixes one policy per Grafx pool and refuses a handle whose observed effective mode differs from configuration. The full whitelist and transition matrix are specified in Okto Grafx's docs/architecture/ST2_DESCRIPTOR_REVALIDATION.md.

MCP admission is intentionally scoped to tool execution. Saturated calls receive a bounded, retryable outcome with next_action.rel=retry_after; initialization, streaming, resources, prompts, and the API/UI listener do not enter this queue.

Data Storage

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

~/.okto-pulse/
|-- data/
|   `-- pulse.db
|-- boards/
|   `-- {board-id}/
|       |-- graph_backend_binding.json
|       `-- grafx/
|           `-- {generation}/
|-- global/
|   |-- graph_backend_binding.json
|   `-- grafx/
|       `-- {generation}/
|-- uploads/
|   `-- {board-id}/
`-- mcp_traces/

[!WARNING] Do not delete graph database directories to "fix" graph errors. Use the KG health and recovery tools so runtime issues remain diagnosable. Pulse 0.4.0 accepts only its current storage format; incompatible storage is refused without conversion or automatic deletion. Select a new storage location for a fresh installation.

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

Restore network access and restart:

okto-pulse serve

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.

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

• configured Board and Global Discovery providers
• Grafx page size (fixed for each existing generation)
• Grafx descriptor revalidation mode (generation for Pulse-managed paths; strict for forensic or externally shared paths)
• KG health and dead-letter metrics

The DLQ Inspector in Settings → Event Queue can redrive an individual row or all accessible rows after their root cause is fixed. Redrive all requires an explicit UI confirmation and drains the board DLQ through bounded 200-row transactions. Both modes are permission-gated, idempotent and wake the consolidation worker.

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

Release Notes

Current: 0.4.0 — BREAKING CHANGE. This release requires a new installation with fresh storage. Data from previous Pulse versions is incompatible and is refused without conversion or automatic deletion; no migration is provided. Community delivers unified validation, structured requirements and verification, separate implementation and verified-delivery progress, and a Grafx-only KG.

→ Full release notes — 0.4.0, 0.3.3, 0.3.2, 0.3.1 and 0.3.0 changesets, plus 0.2.6, 0.2.5, 0.2.3, 0.2.2, 0.2.1 and 0.2.0.

Graph storage

See Local/remote integration and recovery regression for the preserved local changes and their integration with the Grafx-only runtime.

See Open PR review for 0.3.3 for integration decisions, compatibility evidence and deferred dependency migrations.

See CLI, configuration and badge-refresh fixes (#84–#88) for export error behavior, terms storage, CORS configuration and validation evidence.

See Delivery evidence: committed code and test-card verification for the separate Spec completion gate, UI, REST/MCP contracts and audited exemptions.

See Code Evidence Matrix: associations and coverage for the distinction between contextual references and applicable evidence.

See Cognitive Action Center: review knowledge gaps for the human review workflow, waiver effects, failed-processing navigation and permissions.

See KG Health: observe, diagnose and recover for the operations dashboard, contextual help, action impacts and recovery safeguards.

Community uses Okto Grafx only, pinned to the published okto-grafx[accel]==0.0.7 release. uv.lock resolves Grafx from the official PyPI artifacts. See Grafx-only runtime, settings, retirement and data preservation. The Core remains storage-agnostic.

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