@feniix/pi-code-reasoning

Code Reasoning tools for pi and MCP — reflective problem-solving through sequential thinking with branching and revision support.

Based on the MCP server by Matt Westgate, this package defines its tools once with BridgeKit and exposes the same implementation through both pi and MCP adapters.

Features

• Sequential Thinking — Break down complex problems into structured, revisable steps
• Branching — Explore alternative approaches from any thought (🌿)
• Revision — Correct earlier thinking when new insights emerge (🔄)
• Progress Tracking — Track thought count and branches
• Configurable Output — Client-side byte and line truncation

Install

pi install npm:@feniix/pi-code-reasoning

Ephemeral (one-off) use:

pi -e npm:@feniix/pi-code-reasoning

MCP usage

Run the stdio MCP server with npx:

npx -y @feniix/pi-code-reasoning

Example MCP client configuration:

{
  "mcpServers": {
    "code-reasoning": {
      "command": "npx",
      "args": ["-y", "@feniix/pi-code-reasoning"]
    }
  }
}

Use the MCP adapter entrypoint when wiring the same tools into a custom host:

import { createMcpServerOptions, runServer } from "@feniix/pi-code-reasoning/mcp";

// For tests or custom hosts:
const options = createMcpServerOptions();

// For a stdio MCP server entrypoint:
await runServer();

The shared portable tool definitions are available from @feniix/pi-code-reasoning/tools for advanced adapters.

Package entrypoints

Entry point	Purpose
@feniix/pi-code-reasoning/mcp	compiled MCP server helpers
@feniix/pi-code-reasoning/tools	compiled BridgeKit portable tools
@feniix/pi-code-reasoning/extensions/*	compiled compatibility deep imports for extension internals

The pi extension entrypoint remains source-loaded through the package pi.extensions metadata.

Tools

code_reasoning

Record and process a thought with metadata.

Parameter	Type	Required	Description
thought	string	yes	Your reasoning content
thought_number	integer	yes	Position in sequence
total_thoughts	integer	yes	Estimated total thoughts
next_thought_needed	boolean	yes	Set FALSE when done
is_revision	boolean	no	When correcting earlier thought (🔄)
revises_thought	integer	no	Which thought# you're revising
branch_from_thought	integer	no	When exploring alternatives (🌿)
branch_id	string	no	Identifier for the branch
needs_more_thoughts	boolean	no	If more thoughts needed
piMaxBytes	integer	no	Per-call output byte limit, clamped by configured max
piMaxLines	integer	no	Per-call output line limit, clamped by configured max

code_reasoning_status

Get current session status: branches and thought count.

Optional parameters:

Parameter	Type	Required	Description
piMaxBytes	integer	no	Per-call output byte limit, clamped by configured max
piMaxLines	integer	no	Per-call output line limit, clamped by configured max

code_reasoning_reset

Reset the session, clearing all thoughts and branches.

Thinking Patterns

Sequential Thinking (Basic)

{
  "thought": "Initial exploration of the problem...",
  "thought_number": 1,
  "total_thoughts": 5,
  "next_thought_needed": true
}

Branching (Explore Alternatives) 🌿

{
  "thought": "Exploring alternative approach...",
  "thought_number": 3,
  "total_thoughts": 7,
  "next_thought_needed": true,
  "branch_from_thought": 2,
  "branch_id": "alternative-algo-x"
}

Revision (Correct Earlier Thinking) 🔄

{
  "thought": "Revisiting earlier point: Assumption Y was flawed...",
  "thought_number": 4,
  "total_thoughts": 6,
  "next_thought_needed": true,
  "is_revision": true,
  "revises_thought": 2
}

Checklist (Review Every 3 Thoughts)

1. Need to explore alternatives? → Use BRANCH (🌿)
2. Need to correct earlier thinking? → Use REVISION (🔄)
3. Scope changed? → Adjust total_thoughts
4. Done? → Set next_thought_needed = false

Limits

• Thought text is limited to 20,000 characters.
• A session keeps at most 20 thoughts before reset.
• Output limit values must be positive integers.
• When output is truncated, the full output is saved to a temp file when possible. If the temp file cannot be written, the tool output includes a warning instead.

Configuration

CLI Flags

CLI flags apply when running as a pi extension:

pi --code-reasoning-max-bytes=102400 --code-reasoning-max-lines=5000

Environment Variables

Environment variables apply to both pi and MCP runtimes:

export CODE_REASONING_MAX_BYTES=102400
export CODE_REASONING_MAX_LINES=5000
export CODE_REASONING_CONFIG_FILE=/path/to/code-reasoning.json

Settings File

Use pi's standard settings locations for non-secret configuration:

• project: .pi/settings.json
• global: ~/.pi/agent/settings.json

Under the pi-code-reasoning key:

{
  "pi-code-reasoning": {
    "maxBytes": 51200,
    "maxLines": 2000
  }
}

Best practice: use settings.json for non-secret defaults only. If you need a separate private override file, use --code-reasoning-config-file or CODE_REASONING_CONFIG_FILE to point to a custom JSON config file. Legacy aliases --code-reasoning-config and CODE_REASONING_CONFIG are still accepted but deprecated.

CLI Flags

Flag	Env Variable	Default	Description
--code-reasoning-config-file	CODE_REASONING_CONFIG_FILE	—	Custom JSON config file path (overrides settings.json lookup)
--code-reasoning-config	CODE_REASONING_CONFIG	—	Deprecated alias for the config file path
--code-reasoning-max-bytes	CODE_REASONING_MAX_BYTES	51200	Max output bytes
--code-reasoning-max-lines	CODE_REASONING_MAX_LINES	2000	Max output lines

Development

Build the compiled MCP entrypoint locally:

npm run build:mcp --workspace packages/pi-code-reasoning

Run the built stdio server directly:

node packages/pi-code-reasoning/dist/extensions/mcp-server.js

Requirements

• Node.js 22.19.0 or later
• pi v0.51.0 or later when using the pi extension

License

MIT