Decodie UI

A browsable, filterable interface for exploring learning entries generated by the decodie-skill during coding sessions.

Features

• Structured lessons -- entries are automatically grouped into topic-based lessons, sorted by difficulty. Create custom lessons with ordering and per-entry notes.
• Progress tracking -- mark entries as learned and track progress through each lesson with visual indicators.
• Sequential navigation -- step through lessons entry by entry with next/previous controls and a sidebar outline.
• Smart filtering -- filter by experience level, topic, decision type, session, and lifecycle. Switch between lesson and entry views.
• Interactive Q&A -- highlight text and ask follow-up questions via LLM-powered chat with conversation persistence.
• Code references -- content-based anchoring that survives refactoring.
• Syntax highlighting -- code displayed alongside explanations.
• External doc links -- automatic links to php.net, MDN, framework docs, etc.

Prerequisites

• Node.js 18+

Quick Start

Run directly from npm without installing:

npx @owenbush/decodie-ui serve --dir /path/to/project

This starts the server pointing at a project directory that contains a .decodie/ folder. Open http://localhost:8081.

Install the Commands

The Decodie commands for Claude Code can be installed with a single command:

npx @owenbush/decodie-ui install-skill

This downloads the command files from the decodie-skill repo into ~/.claude/commands/decodie/, giving you:

• /decodie:observe — Document decisions as you code
• /decodie:analyze — Analyze existing code retroactively
• /decodie:ask — Ask questions about entries

To install at project level instead (shared with your team):

npx @owenbush/decodie-ui install-skill --scope project

Development

git clone https://github.com/owenbush/decodie-ui.git
cd decodie-ui
npm install
npx tsx src/cli.ts serve --dir /path/to/project

Production

npm run build
node dist/cli.js serve --dir /path/to/project

Q&A Setup

Q&A lets you ask follow-up questions about any learning entry. Credentials are stored in .decodie/.env (not tracked by git). Set one of the following:

• CLAUDE_CODE_OAUTH_TOKEN -- uses your Claude Pro/Max subscription (run claude setup-token to obtain a token).
• CLAUDE_API_KEY -- pay-per-token billing (get a key at console.anthropic.com).

The Settings page in the UI shows setup instructions.

Conversation Persistence

Q&A conversations are saved to .decodie/conversations/ as JSON files (one per entry) and persist across sessions. Revisit any entry to pick up where you left off.

API Endpoints

Method	Path	Description
GET	/api/status	Service health and entry statistics
GET	/api/entries	List entries with filtering support
GET	/api/entries/:id	Get a single entry with full content
PATCH	/api/entries/:id	Update entry fields (lifecycle, pinned)
GET	/api/config	Read user configuration
GET	/api/lessons	List all lessons (auto-generated + custom)
GET	/api/lessons/:id	Get lesson detail with ordered entries
POST	/api/lessons	Create a custom lesson
PUT	/api/lessons/:id	Update a custom lesson
DELETE	/api/lessons/:id	Delete a custom lesson
GET	/api/progress	Get progress data (learned entries)
POST	/api/progress/:entryId/learn	Mark an entry as learned
DELETE	/api/progress/:entryId/learn	Unmark an entry as learned
GET	/api/qa/status	Check whether Q&A is enabled
POST	/api/qa	Ask a question about an entry (SSE stream)
GET	/api/conversations	List entry IDs that have saved conversations
GET	/api/conversations/:entryId	Get a saved conversation
PUT	/api/conversations/:entryId	Save or update a conversation
DELETE	/api/conversations/:entryId	Delete a saved conversation

Tests

npm test

Data Format

The .decodie/ directory structure and JSON schemas are defined in the decodie-skill repository under schema/.

Related Repositories

• owenbush/decodie -- Main site and documentation.
• owenbush/decodie-skill -- The skill that generates .decodie/ data during coding sessions.
• owenbush/decodie-ddev -- DDEV add-on that serves this UI as a DDEV service.
• owenbush/decodie-github-action -- GitHub Action for automatic PR analysis. View on Marketplace.
• owenbush/decodie-github-bot -- Interactive bot for on-demand analysis and explanations in PR comments.
• owenbush/decodie-vscode -- VSCode extension with sidebar entry browser and right-click analysis. Install from Marketplace.
• owenbush/decodie-core -- Shared data layer used by this UI and the VSCode extension.