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