Metadata-Version: 2.4
Name: okto-pulse
Version: 0.3.0
Summary: Okto Pulse — spec-driven project management with AI agents via MCP. Local-first, single command setup.
Project-URL: Homepage, https://github.com/OktoLabsAI/okto-pulse
Project-URL: Documentation, https://github.com/OktoLabsAI/okto-pulse#readme
Project-URL: Repository, https://github.com/OktoLabsAI/okto-pulse
Project-URL: Issues, https://github.com/OktoLabsAI/okto-pulse/issues
Project-URL: Changelog, https://github.com/OktoLabsAI/okto-pulse/blob/main/CHANGELOG.md
Author-email: Okto Labs <dev@oktolabs.ai>
License: Elastic-2.0
License-File: LICENSE
Keywords: ai-agents,claude,cursor,developer-tools,kanban,mcp,project-management,spec-driven,windsurf
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Scheduling
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: aiosqlite<1.0.0,>=0.19.0
Requires-Dist: anyio<5.0.0,>=4.0.0
Requires-Dist: apscheduler<4.0.0,>=3.10.0
Requires-Dist: chardet<6.0.0,>=3.0.2
Requires-Dist: fastapi!=0.137.0,<1.0.0,>=0.109.0
Requires-Dist: fastmcp<3.0.0,>=2.0.0
Requires-Dist: filelock<4.0.0,>=3.16.0
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: ladybug<0.17.0,>=0.16.0
Requires-Dist: mcp<2.0.0,>=1.20.0
Requires-Dist: okto-pulse-core<1.0.0,>=0.3.0
Requires-Dist: pydantic-settings<3.0.0,>=2.1.0
Requires-Dist: pydantic<2.14,>=2.5.0
Requires-Dist: python-multipart<1.0.0,>=0.0.6
Requires-Dist: requests<3.0.0,>=2.32.0
Requires-Dist: sentence-transformers<6.0.0,>=2.5.0
Requires-Dist: sqlalchemy[asyncio]<3.0.0,>=2.0.0
Requires-Dist: starlette<1.0.0,>=0.35.0
Requires-Dist: uvicorn[standard]<1.0.0,>=0.27.0
Requires-Dist: wsproto<2.0.0,>=1.2.0
Description-Content-Type: text/markdown

# Okto Pulse

<div align="center">
  <h3><em>Spec-driven project management for AI-assisted development.</em></h3>
</div>

<p align="center">
  <strong>Okto Pulse turns ideas, refinements, specs, tasks, tests and bugs into a governed SDLC board that AI agents can operate through MCP.</strong>
</p>

<p align="center">
  <strong>Ship with AI. Stay in control.</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/okto-pulse/"><img src="https://img.shields.io/pypi/v/okto-pulse" alt="PyPI version"></a>
  <a href="https://pypi.org/project/okto-pulse/"><img src="https://img.shields.io/pypi/pyversions/okto-pulse" alt="Python versions"></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Elastic%202.0-blue" alt="License"></a>
  <a href="https://github.com/OktoLabsAI/okto-pulse-core"><img src="https://img.shields.io/badge/core-okto--pulse--core-6f42c1" alt="Core repository"></a>
</p>

---

## Table of Contents

- [What is Okto Pulse?](#what-is-okto-pulse)
- [Platform Surface](#platform-surface)
- [Get Started](#get-started)
- [Connect an AI Coding Agent](#connect-an-ai-coding-agent)
- [Token Usage](#token-usage)
- [Core Workflow](#core-workflow)
- [Governance Gates](#governance-gates)
- [Knowledge Graph](#knowledge-graph)
- [Architecture](#architecture)
- [CLI Reference](#cli-reference)
- [Run with Docker](#run-with-docker)
- [Data Storage](#data-storage)
- [From Source](#from-source)
- [Troubleshooting](#troubleshooting)
- [Release Notes](#release-notes)
- [License](#license)

**Reference documents**

| Document | Contents |
| --- | --- |
| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Dependency owner matrix, adapter source map and the **port → adapter matrix** |
| [`docs/RELEASE-NOTES.md`](docs/RELEASE-NOTES.md) | Full changeset per version |
| [`docs/TOKEN-USAGE.md`](docs/TOKEN-USAGE.md) | Measured MCP context cost for agents |
| [`docs/kg-health.md`](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:

```text
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

```bash
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:

```bash
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

```bash
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:

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

If you change the MCP port, regenerate the file:

```bash
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](docs/TOKEN-USAGE.md)** — 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](docs/ARCHITECTURE.md)** — 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

```bash
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:

```bash
docker exec okto-pulse okto-pulse api-key
```

### Compose

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

```bash
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:

```bash
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/`:

```text
~/.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:

```bash
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:

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

Build the frontend before packaging:

```bash
cd frontend
npm install
npm run build
cd ..
```

## Troubleshooting

<details>
<summary>Embedding model did not download</summary>

Restore network access and restart:

```bash
okto-pulse serve
```

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

```bash
python scripts/smoke_embedding.py
```

</details>

<details>
<summary>AI agent cannot connect to MCP</summary>

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

```bash
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.

</details>

<details>
<summary>Graph database reports lock, WAL or size errors</summary>

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.

</details>

## 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](docs/RELEASE-NOTES.md)** — 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.

<!-- AF33-CAPSTONE-MATRIX:BEGIN -->
| 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 |
<!-- AF33-CAPSTONE-MATRIX:END -->

<!-- F16-SAAS-CLOSURE:BEGIN -->
| 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 |
<!-- F16-SAAS-CLOSURE:END -->

## License

[Elastic License 2.0](./LICENSE) - 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
