Odradek

English | 简体中文

Preface

This project warmly welcomes Vibe Coding developers to join and contribute. Currently in its early stages, the project may have some imperfections. We sincerely invite everyone to contribute code, provide feedback, and help us improve it together.

Overview

Odradek is a CLI tool for diagnosing and enhancing Claude Code, Codex, and similar AI coding Agents. It enables you to:

• Chat with LLMs directly in the terminal while running diagnostics
• Parse agent session logs to understand token structures and context pressure
• Perform multi-dimensional noise evaluation to identify potential issues
• Scan and inventory prompt assets, rules, and Skill documentation
• Seamlessly switch between multiple providers (Claude / OpenRouter / Qwen)

Core Features

Preview

Feature Areas

Requirements

• Node.js >= 20
• npm >= 9

Install

Install globally:

npm install -g odradek-cli
odradek

Or run it once:

npx odradek-cli@latest

Quick Start

1. Configure environment variables or a .env file for your provider
2. Start the CLI with odradek
3. Trust the current workspace when prompted
4. Run diagnostic commands

/state                    # Check runtime status
/provider                 # Confirm current provider
/scan_tokens codex current  # Parse session token structure
/token_usage codex current  # Aggregate daily token usage by model
/noise_eval codex current   # Run Evidence-first noise evaluation

Swap codex for claude to analyze Claude logs instead.

Configuration

Odradek loads configuration from:

1. shell environment variables
2. app-level .env / .env.local
3. workspace .env / .env.local files from repo root down to the current directory
4. local config file defaults

Existing shell env vars win. Among .env files, the closer workspace file overrides broader defaults.

Recommended app-level .env path:

Windows: %APPDATA%/odradek-cli/.env
macOS:   ~/Library/Application Support/odradek-cli/.env
Linux:   ~/.config/odradek-cli/.env

Local config file path:

Windows: %APPDATA%/odradek-cli/config.json
macOS:   ~/Library/Application Support/odradek-cli/config.json
Linux:   ~/.config/odradek-cli/config.json

Runtime Provider Examples

Claude:

ODRADEK_ACTIVE_PROVIDER=claude
ODRADEK_CLAUDE_API_KEY=your_claude_api_key
ODRADEK_CLAUDE_BASE_URL=https://api.anthropic.com/v1
# ODRADEK_CLAUDE_MODEL=claude-sonnet-4-20250514
ODRADEK_PROJECT_CONTEXT_ENABLED=true

OpenRouter:

ODRADEK_ACTIVE_PROVIDER=openrouter
ODRADEK_OPENROUTER_API_KEY=your_openrouter_api_key
ODRADEK_OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
ODRADEK_OPENROUTER_MODEL=provider/model-name
ODRADEK_PROJECT_CONTEXT_ENABLED=true

Qwen:

ODRADEK_ACTIVE_PROVIDER=qwen
ODRADEK_QWEN_API_KEY=your_dashscope_api_key
ODRADEK_QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
ODRADEK_QWEN_MODEL=qwen3.5-plus
ODRADEK_PROJECT_CONTEXT_ENABLED=true

Environment Variables

Layered System Prompts

Odradek can assemble layered system prompts before each model request.

Workspace prompt paths:

.odradek/system-prompts/base.md
.odradek/system-prompts/providers/<provider>.md
.odradek/system-prompts/models/<model>.md

App-level prompt path:

%APPDATA%/odradek-cli/system-prompts/

Load order:

1. app-level base.md
2. app-level providers/<provider>.md
3. app-level models/<model>.md
4. workspace .odradek/system-prompts/base.md
5. workspace .odradek/system-prompts/providers/<provider>.md
6. workspace .odradek/system-prompts/models/<model>.md

Commands

Runtime and workspace

Prompt and workspace inspection

Claude and Codex diagnostics

These commands support the source prefix claude or codex:

Useful examples:

/scan_tokens codex current
/token_usage codex current
/context_health codex all
/noise_eval claude current
/todo_granularity codex current

Cost estimation

The /cost command provides real-time cost estimation by:

• Fetching live pricing data from OpenRouter's model catalog
• Scanning the current workspace prompt assets to calculate total input tokens
• Modeling multiple cost scenarios (cold start, cache hits, combined with output)
• Displaying visual breakdowns of cache-eligible vs dynamic tokens

Useful examples:

/cost claude    # Estimate costs for Claude family models
/cost codex     # Estimate costs for Codex/GPT family models

Note: /cost cursor is intentionally not supported as Cursor model pricing is not publicly available.

Conversation and export

Exports are written to:

.odradek/exports/

Example:

/export codex all
/export claude noise_eval

Development

npm install

Copy the env template:

cp .env.example .env

PowerShell:

Copy-Item .env.example .env

Run the dev CLI:

npm run dev

Build and run the compiled version:

npm run build
npm start

Optional local link:

npm link
odradek

Undo the global link:

npm unlink -g odradek-cli

Core scripts:

npm run dev
npm run build
npm start

Project Layout

src/
|- cli/                    # CLI core: command registry, handlers, session management
|   |- ink/                # Ink terminal UI components
|   |- ClaudeTranscriptParser.ts   # Claude/Codex session parser
|   |- NoiseEvaluator.ts            # Evidence-first noise evaluation engine
|   |- ContextNoiseAnalyzer.ts      # Context noise analysis
|   |- PromptAssetScanner.ts       # Prompt asset scanner
|   |- RuleScanner.ts              # Rule extractor
|   |- SkillScanner.ts             # SKILL.md inventory
|   |- TodoGranularityAnalyzer.ts   # Todo granularity analysis
|   |- ConversationManager.ts       # Conversation history management
|   |- ConfigStore.ts              # Configuration storage
|   `- tokenEstimate.ts            # Token estimation
|- config/                  # Config loading, Provider catalog
|- llm/                     # LLM adapter layer: multi-provider support
|   |- adapters/             # Claude / OpenRouter / Qwen adapters
|   |- LLMClient.ts         # LLM client
|   |- ProjectContextBuilder.ts    # Project context injection
|   `- PersistentProjectIndex.ts   # Persistent project index
`- index.ts                 # CLI entry point

Release

npm run build
npm pack --dry-run
npm publish

For a scoped public package:

npm publish --access public

Report Bugs

Issues and suggestions are welcome in GitHub Issues.

About

As an independent developer, I welcome technical discussion, collaboration, and career opportunities.

Star History