Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.oktolabs.ai/llms.txt

Use this file to discover all available pages before exploring further.

Prerequisites
  • Pulse installed and serving? If not → Install
  • Agent connected via MCP? If not → MCP Setup
This walkthrough uses a concrete example — adding user authentication — so every step has a visible output. The CLI path uses Claude Code; the UI path works for any browser.
1

Create a board

okto-pulse init already created a default board when you installed. Verify it’s there:Via MCP (Claude Code):
> list my boards
Claude Code calls okto_pulse_list_my_boards and returns:
[
  {
    "id": "a1b2c3d4-...",
    "name": "My Project",
    "created_at": "2026-05-07T10:00:00Z"
  }
]
Via UI:Open localhost:8100. The board is already selected in the sidebar. You don’t need to create one.If you want a dedicated board for this project:
# From Claude Code:
> create a board called "Auth Project"

# From UI:
# Settings → Boards → New Board
2

Create an ideation

Ideations are where raw requests land before anything gets built.Via MCP (Claude Code):
> create an ideation: "I want to add user authentication to my app"
Pulse calls okto_pulse_create_ideation and returns:
{
  "id": "9c64cdac-...",
  "title": "Add user authentication",
  "raw_request": "I want to add user authentication to my app",
  "status": "draft",
  "scope_assessment": null
}
Via UI:Ideations tab → New Ideation → paste your raw request → Save.The ideation is now in draft state. Pulse has not made any decisions yet.
3

Watch Pulse ask the ambiguity-killer questions

This is the step that makes Pulse different from a rules file.Pulse analyzes your ideation and surfaces every material gap before you write a line of spec. Ask it to evaluate:
> evaluate ideation 9c64cdac
Pulse runs okto_pulse_evaluate_ideation and returns a scope assessment:
{
  "domains": 3,
  "ambiguity": 4,
  "dependencies": 2,
  "ambiguity_notes": "Auth strategy unspecified (OAuth, password, passkey); session management approach unclear; email verification scope undefined"
}
Ambiguity is 4/5 — Pulse won’t let this become a spec yet. It asks:
> ask ideation questions
Pulse calls okto_pulse_ask_ideation_choice_question:
Q1 (choice): Which authentication strategy should we use?
  A. Email + password with bcrypt hashing
  B. OAuth only (Google, GitHub)
  C. Both: password-based with optional OAuth link
  D. Passkeys / WebAuthn (passwordless)
You (or the agent) answers:
> answer: A — email + password with bcrypt
Pulse records the answer via okto_pulse_answer_ideation_question:
{
  "question_id": "q-001",
  "answer": "Email + password with bcrypt hashing",
  "answered_by": "agent:claude-code",
  "timestamp": "2026-05-07T10:03:41Z"
}
Pulse continues for each gap. When ambiguity drops below the threshold, it marks the ideation ready_for_refinement.
You can ask all the questions in one shot: > run the ambiguity-killer protocol on ideation 9c64cdacPulse will call ask_ideation_question for each gap, accept your answers, and re-evaluate. Typical ideation takes 4–7 questions.
4

Move to spec — derived, not typed

Once the ideation is evaluated, derive the spec. Pulse builds it from your answers — you don’t type a spec from scratch.
> derive spec from ideation 9c64cdac
Pulse calls okto_pulse_derive_spec_from_ideation and returns a populated spec:
{
  "id": "spec-8a3f...",
  "title": "User Authentication — Email + Password",
  "problem_statement": "The application has no authentication layer. Users cannot register, log in, or maintain sessions.",
  "acceptance_criteria": [
    "User can register with email and password",
    "Password is stored as bcrypt hash (cost factor ≥ 12)",
    "User can log in and receive a session token",
    "Invalid credentials return 401 with no information leakage",
    "Session expires after 30 days of inactivity"
  ],
  "functional_requirements": ["..."],
  "test_scenarios": [],
  "business_rules": [],
  "status": "draft"
}
The spec is pre-populated from your ideation answers. The acceptance criteria came from your answer to Q1 and Pulse’s domain knowledge. You didn’t write them.Review and refine in the UI (Specs tab → open spec → edit inline), or via MCP:
> add acceptance criterion: "Password reset via email link with 1-hour expiry"
When the spec looks right:
> submit spec evaluation
Pulse calls okto_pulse_submit_spec_evaluation. If coverage meets thresholds (acceptance criteria ≥ 80%, test scenarios linked), the spec moves to approved.
5

Create the first card and move it to in-progress

Cards are execution units. Each one traces back to the spec you just created.
> suggest sprints for spec spec-8a3f
Pulse calls okto_pulse_suggest_sprints and proposes a sprint slice. Accept it:
> create sprint "Auth Sprint 1" with objective "Ship registration and login endpoints"
Then create the first card:
> create card: "Implement POST /auth/register endpoint"
  type: task
  description: "Register endpoint: accept email + password, validate format, hash with bcrypt (cost 12), store user, return 201 + user ID. Return 409 on duplicate email."
  sprint: Auth Sprint 1
Pulse calls okto_pulse_create_card. The card is created in pending state, linked to the spec and sprint.Move it to active work:
> move card to in_progress
Via UI:Drag the card from the Pending column to In Progress on the board.The board now shows one active card, a sprint, a spec, and an ideation — all connected.

​
What just happened

You went from a vague idea to a tracked, traceable card in 5 minutes. Here’s what Pulse actually did:
  • The KG now contains a Decision node. The answer “email + password with bcrypt” was written to the knowledge graph as a Decision with type AuthStrategy. Any future ideation about login, session management, or password reset will surface this decision automatically — before a new agent accidentally decides something contradictory.
  • Your agent can query that decision mid-task. At any point during implementation, Claude Code (or Cursor, or Cline) can call okto_pulse_kg_query_natural("What auth approach did we decide?") and get the answer back from the graph — not from context window memory. The answer is there whether the session is 2 minutes old or 2 months old.
  • Everything survives the next session. The ideation, Q&A, spec, sprint, and KG decision nodes are stored in SQLite + the embedded graph at ~/.okto-pulse/boards/{id}/graph.lbug. Start a new Claude Code session tomorrow, point it at the same board, and it has full context — without you re-explaining anything.

Knowledge Graph

What Pulse wrote to the graph just now, and how your agent queries it mid-task.

MCP Setup

Full agent configuration for Claude Code, Cursor, Cline, Windsurf, Goose, and Codex.
Last modified on May 8, 2026