@voxcode-dev/voxcode 0.1.0 → 0.1.2

package/docs/sessions.md

@@ -1,17 +1,55 @@
 # Sessions
 
-Sessions capture conversation history, context, and execution state.
+Sessions keep context across long coding tasks so you can continue without restating everything.
 
-## What Sessions Enable
+## Why Sessions Matter
 
-- Continue work across terminal restarts
-- Branch and compare approaches
-- Keep iterative coding loops coherent
+- Preserve task history, decisions, and tool outputs
+- Resume complex work after terminal restarts
+- Compare approaches by branching session state
 
-## Session Workflow
+## Basic Operations
 
-1. Start a session in interactive mode.
-2. Resume by selecting a prior session.
-3. Compact when history gets too large.
+### Start a new session
 
-See [session-format.md](session-format.md) and [compaction.md](compaction.md).
+```bash
+vox
+```
+
+### Continue latest session
+
+```bash
+vox --continue
+```
+
+### Continue by interactive selection
+
+Launch `vox` and select from session history in the UI.
+
+## Session Branching
+
+Branching is useful when you want to test alternatives without losing the original path:
+
+- branch A: minimal patch
+- branch B: larger refactor
+
+This keeps experiment history explicit and reviewable.
+
+## Compaction
+
+Long sessions can exceed model context. Compaction summarizes prior history while preserving critical facts.
+
+Use compaction when:
+
+- prompts start to get slower
+- repeated context appears in every turn
+- model behavior degrades due to context overload
+
+## Best Practices
+
+- Name sessions by objective (e.g., `auth-middleware-hardening`)
+- Keep one goal per session when possible
+- Compact periodically for long-running tasks
+- Record verification results in the session before finishing
+
+For details of on-disk format, see [session-format.md](session-format.md).

package/docs/settings.md

@@ -1,15 +1,52 @@
-# Settings
+# Settings and Configuration
 
-Voxcode settings control runtime behavior, providers, model defaults, UI, and safety features.
+Voxcode can be configured through environment variables and runtime settings.
 
-## Common Categories
+## Configuration Layers
 
-- Provider credentials and defaults
-- Model routing and fallback
-- Session and history behavior
-- TUI preferences
-- Telemetry and offline controls
+1. **Environment variables**: best for secrets and CI runtime behavior
+2. **Config files**: best for stable defaults and team conventions
+3. **CLI flags**: best for one-off overrides
 
-## Recommendation
+## Common Environment Variables
 
-Keep team defaults minimal, and override per-user where needed.
+| Variable | Purpose |
+| --- | --- |
+| `VOXCODE_OFFLINE` | Disable network-dependent features where possible |
+| `VOXCODE_SKIP_VERSION_CHECK` | Skip update/version check logic |
+| `VOXCODE_TELEMETRY` | Toggle telemetry behavior |
+| `VOXCODE_CONFIG_DIR` | Override default config directory |
+| `VOXCODE_SHARE_VIEWER_URL` | Customize share viewer endpoint |
+| `VOXCODE_TUI_DEBUG` | Enable TUI debug behavior |
+
+Provider secrets (examples):
+
+- `ANTHROPIC_API_KEY`
+- `OPENAI_API_KEY`
+- `GEMINI_API_KEY`
+- `MISTRAL_API_KEY`
+
+## Recommended Setup Pattern
+
+- Keep provider keys in shell env or secret manager
+- Commit non-secret defaults in project config
+- Override per session when needed
+
+## Example: Shell Profile
+
+```bash
+export ANTHROPIC_API_KEY="your-key"
+export VOXCODE_TELEMETRY="0"
+```
+
+## Example: Per-Command Override
+
+```bash
+VOXCODE_OFFLINE=1 vox -p "Analyze local files only"
+```
+
+## Troubleshooting
+
+- config not applied: verify variable name and shell scope
+- provider auth errors: verify key is exported in current shell
+- inconsistent behavior: check for conflicting env vars and CLI flags

package/docs/skills.md

@@ -1,18 +1,39 @@
 # Skills
 
-Skills are reusable instruction packs for common workflows.
+Skills are reusable workflow instructions that package domain knowledge for repeatable tasks.
 
-## Why Skills
+## Why Use Skills
 
-- Standardize repeated tasks
-- Reduce prompt boilerplate
-- Improve consistency across contributors
+- standardize team workflows
+- reduce repeated prompt boilerplate
+- improve consistency and output quality
 
-## Typical Uses
+## Typical Skill Scenarios
 
-- Debugging workflows
-- Documentation generation
-- Refactor procedures
-- Release and verification checklists
+- bug triage and incident debugging
+- release checklist automation
+- documentation generation
+- refactor planning and verification
 
-Skills can be project-local or shared across teams.
+## Skill Authoring Basics
+
+1. Define a narrow objective
+2. Include clear constraints
+3. Require verification steps
+4. Keep output contract explicit
+
+## Good Skill Design
+
+- **specific**: one job per skill
+- **deterministic**: same input -> similar output shape
+- **safe**: includes guardrails for destructive operations
+- **verifiable**: asks for concrete checks and evidence
+
+## Team Adoption Pattern
+
+- start with 2-3 high-frequency workflows
+- review outputs and iterate prompts
+- store skills in version control
+- add ownership and maintenance notes
+
+For examples and related extension patterns, see [extensions.md](extensions.md).

package/docs/usage.md

@@ -1,19 +1,73 @@
 # Usage Guide
 
-## Interactive
+This guide covers day-to-day Voxcode usage in interactive and scripted modes.
+
+## Interactive Mode
+
+Start the TUI:
+
+```bash
+vox
+```
+
+Use interactive mode when you want to:
+
+- iterate on complex changes
+- inspect and edit multiple files
+- run validation commands in loop
+- preserve context over time
+
+## One-Shot Prompt Mode
+
+Run a single instruction and exit:
 
 ```bash
-voxcode
+vox -p "Generate unit tests for src/parser.ts"
 ```
 
-Use interactive mode for exploratory coding, debugging, and iterative tasks.
+Use this for quick automation and shell scripts.
 
-## One-Shot Prompt
+## JSON / Machine-Friendly Output
 
 ```bash
-voxcode -p "Write tests for src/parser.ts"
+vox --json -p "Summarize current git diff"
 ```
 
-## Automation
+Useful for CI pipelines and tool integrations.
+
+## Typical Workflow Pattern
+
+1. Ask Voxcode to inspect relevant files
+2. Request a small safe change
+3. Run tests/lint/build
+4. Review output and iterate
+5. Commit once verified
+
+## Prompting Tips
+
+- Be explicit about **scope** (which files, which feature)
+- Include **constraints** (no API break, keep backward compatibility)
+- Request **verification** (tests, typecheck, lint)
+- Ask for **summary with file paths**
+
+Example:
+
+```text
+Refactor `src/session.ts` to reduce duplicated logic, keep API unchanged, run tests, and summarize all modified files.
+```
+
+## Working with Existing Repositories
+
+- Start from repo root
+- Mention target package/path in your prompt
+- Prefer incremental changes over broad rewrites
+
+## Continuing Work
+
+Resume previous context:
+
+```bash
+vox --continue
+```
 
-Use JSON or RPC mode for integration into scripts and tools.
+See [sessions.md](sessions.md) for branching and compaction.

package/examples/extensions/README.md

@@ -137,7 +137,7 @@ cp permission-gate.ts ~/.pi/agent/extensions/
 See [docs/extensions.md](../../docs/extensions.md) for full documentation.
 
 ```typescript
-import type { ExtensionAPI } from "@voxcode/voxcode";
+import type { ExtensionAPI } from "@voxcode-dev/voxcode";
 import { Type } from "typebox";
 
 export default function (pi: ExtensionAPI) {
@@ -179,7 +179,7 @@ export default function (pi: ExtensionAPI) {
 
 **Use StringEnum for string parameters** (required for Google API compatibility):
 ```typescript
-import { StringEnum } from "@voxcode/voxcode-ai";
+import { StringEnum } from "@voxcode-dev/voxcode-ai";
 
 // Good
 action: StringEnum(["list", "add"] as const)

package/examples/extensions/auto-commit-on-exit.ts

@@ -5,7 +5,7 @@
  * Uses the last assistant message to generate a commit message.
  */
 
-import type { ExtensionAPI } from "@voxcode/voxcode";
+import type { ExtensionAPI } from "@voxcode-dev/voxcode";
 
 export default function (pi: ExtensionAPI) {
 	pi.on("session_shutdown", async (_event, ctx) => {

package/examples/extensions/bash-spawn-hook.ts

@@ -7,8 +7,8 @@
  *   pi -e ./bash-spawn-hook.ts
  */
 
-import type { ExtensionAPI } from "@voxcode/voxcode";
-import { createBashTool } from "@voxcode/voxcode";
+import type { ExtensionAPI } from "@voxcode-dev/voxcode";
+import { createBashTool } from "@voxcode-dev/voxcode";
 
 export default function (pi: ExtensionAPI) {
 	const cwd = process.cwd();

package/examples/extensions/bookmark.ts

@@ -7,7 +7,7 @@
  * Usage: /bookmark [label] - bookmark the last assistant message
  */
 
-import type { ExtensionAPI } from "@voxcode/voxcode";
+import type { ExtensionAPI } from "@voxcode-dev/voxcode";
 
 export default function (pi: ExtensionAPI) {
 	pi.registerCommand("bookmark", {

package/examples/extensions/border-status-editor.ts

@@ -1,6 +1,6 @@
-import { CustomEditor, type ExtensionAPI, type ExtensionContext, type KeybindingsManager } from "@voxcode/voxcode";
-import type { Component, EditorTheme, TUI } from "@voxcode/voxcode-tui";
-import { truncateToWidth, visibleWidth } from "@voxcode/voxcode-tui";
+import { CustomEditor, type ExtensionAPI, type ExtensionContext, type KeybindingsManager } from "@voxcode-dev/voxcode";
+import type { Component, EditorTheme, TUI } from "@voxcode-dev/voxcode-tui";
+import { truncateToWidth, visibleWidth } from "@voxcode-dev/voxcode-tui";
 
 function fitBorder(
 	left: string,

package/examples/extensions/built-in-tool-renderer.ts

@@ -25,9 +25,9 @@
  *   pi -e ./built-in-tool-renderer.ts
  */
 
-import type { BashToolDetails, EditToolDetails, ExtensionAPI, ReadToolDetails } from "@voxcode/voxcode";
-import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@voxcode/voxcode";
-import { Text } from "@voxcode/voxcode-tui";
+import type { BashToolDetails, EditToolDetails, ExtensionAPI, ReadToolDetails } from "@voxcode-dev/voxcode";
+import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@voxcode-dev/voxcode";
+import { Text } from "@voxcode-dev/voxcode-tui";
 
 export default function (pi: ExtensionAPI) {
 	const cwd = process.cwd();

package/examples/extensions/claude-rules.ts

@@ -19,7 +19,7 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { ExtensionAPI } from "@voxcode/voxcode";
+import type { ExtensionAPI } from "@voxcode-dev/voxcode";
 
 /**
  * Recursively find all .md files in a directory

package/examples/extensions/commands.ts

@@ -10,7 +10,7 @@
  * 3. Use /commands extensions to filter by source
  */
 
-import type { ExtensionAPI, SlashCommandInfo } from "@voxcode/voxcode";
+import type { ExtensionAPI, SlashCommandInfo } from "@voxcode-dev/voxcode";
 
 export default function commandsExtension(pi: ExtensionAPI) {
 	pi.registerCommand("commands", {

package/examples/extensions/confirm-destructive.ts

@@ -5,7 +5,7 @@
  * Demonstrates how to cancel session events using the before_* events.
  */
 
-import type { ExtensionAPI, SessionBeforeSwitchEvent, SessionMessageEntry } from "@voxcode/voxcode";
+import type { ExtensionAPI, SessionBeforeSwitchEvent, SessionMessageEntry } from "@voxcode-dev/voxcode";
 
 export default function (pi: ExtensionAPI) {
 	pi.on("session_before_switch", async (event: SessionBeforeSwitchEvent, ctx) => {

package/examples/extensions/custom-compaction.ts

@@ -13,9 +13,9 @@
  *   pi --extension examples/extensions/custom-compaction.ts
  */
 
-import type { ExtensionAPI } from "@voxcode/voxcode";
-import { convertToLlm, serializeConversation } from "@voxcode/voxcode";
-import { complete } from "@voxcode/voxcode-ai";
+import type { ExtensionAPI } from "@voxcode-dev/voxcode";
+import { convertToLlm, serializeConversation } from "@voxcode-dev/voxcode";
+import { complete } from "@voxcode-dev/voxcode-ai";
 
 export default function (pi: ExtensionAPI) {
 	pi.on("session_before_compact", async (event, ctx) => {

package/examples/extensions/custom-footer.ts

@@ -8,9 +8,9 @@
  * Token stats come from ctx.sessionManager/ctx.model (already accessible).
  */
 
-import type { ExtensionAPI } from "@voxcode/voxcode";
-import type { AssistantMessage } from "@voxcode/voxcode-ai";
-import { truncateToWidth, visibleWidth } from "@voxcode/voxcode-tui";
+import type { ExtensionAPI } from "@voxcode-dev/voxcode";
+import type { AssistantMessage } from "@voxcode-dev/voxcode-ai";
+import { truncateToWidth, visibleWidth } from "@voxcode-dev/voxcode-tui";
 
 export default function (pi: ExtensionAPI) {
 	let enabled = false;

package/examples/extensions/custom-header.ts

@@ -5,8 +5,8 @@
  * (logo + keybinding hints) with a custom component showing the pi mascot.
  */
 
-import type { ExtensionAPI, Theme } from "@voxcode/voxcode";
-import { VERSION } from "@voxcode/voxcode";
+import type { ExtensionAPI, Theme } from "@voxcode-dev/voxcode";
+import { VERSION } from "@voxcode-dev/voxcode";
 
 // --- PI MASCOT ---
 // Based on pi_mascot.ts - the pi agent character

package/examples/extensions/custom-provider-anthropic/index.ts

@@ -23,7 +23,7 @@
 
 import Anthropic from "@anthropic-ai/sdk";
 import type { ContentBlockParam, MessageCreateParamsStreaming } from "@anthropic-ai/sdk/resources/messages.js";
-import type { ExtensionAPI } from "@voxcode/voxcode";
+import type { ExtensionAPI } from "@voxcode-dev/voxcode";
 import {
 	type Api,
 	type AssistantMessage,
@@ -43,7 +43,7 @@ import {
 	type Tool,
 	type ToolCall,
 	type ToolResultMessage,
-} from "@voxcode/voxcode-ai";
+} from "@voxcode-dev/voxcode-ai";
 
 // =============================================================================
 // OAuth Implementation (copied from packages/voxcode-ai/src/utils/oauth/anthropic.ts)

package/examples/extensions/custom-provider-gitlab-duo/index.ts

@@ -9,7 +9,7 @@
  *   # Then /login gitlab-duo, or set GITLAB_TOKEN=glpat-...
  */
 
-import type { ExtensionAPI } from "@voxcode/voxcode";
+import type { ExtensionAPI } from "@voxcode-dev/voxcode";
 import {
 	type Api,
 	type AssistantMessageEventStream,
@@ -21,7 +21,7 @@ import {
 	type SimpleStreamOptions,
 	streamSimpleAnthropic,
 	streamSimpleOpenAIResponses,
-} from "@voxcode/voxcode-ai";
+} from "@voxcode-dev/voxcode-ai";
 
 // =============================================================================
 // Constants

package/examples/extensions/custom-provider-gitlab-duo/test.ts

@@ -8,7 +8,7 @@
  *   npx tsx test.ts claude-sonnet-4-5-20250929 --thinking
  */
 
-import { type Api, type Context, type Model, registerApiProvider, streamSimple } from "@voxcode/voxcode-ai";
+import { type Api, type Context, type Model, registerApiProvider, streamSimple } from "@voxcode-dev/voxcode-ai";
 import { readFileSync } from "fs";
 import { getAgentDir } from "packages/voxcode/src/config.js";
 import { join } from "path";

package/examples/extensions/dirty-repo-guard.ts

@@ -5,7 +5,7 @@
  * Useful to ensure work is committed before switching context.
  */
 
-import type { ExtensionAPI, ExtensionContext } from "@voxcode/voxcode";
+import type { ExtensionAPI, ExtensionContext } from "@voxcode-dev/voxcode";
 
 async function checkDirtyRepo(
 	pi: ExtensionAPI,

package/examples/extensions/doom-overlay/doom-component.ts

@@ -5,8 +5,8 @@
  * Height is calculated from width to maintain DOOM's aspect ratio.
  */
 
-import type { Component } from "@voxcode/voxcode-tui";
-import { isKeyRelease, type TUI } from "@voxcode/voxcode-tui";
+import type { Component } from "@voxcode-dev/voxcode-tui";
+import { isKeyRelease, type TUI } from "@voxcode-dev/voxcode-tui";
 import type { DoomEngine } from "./doom-engine.ts";
 import { DoomKeys, mapKeyToDoom } from "./doom-keys.ts";
 

package/examples/extensions/doom-overlay/doom-keys.ts

@@ -34,7 +34,7 @@ export const DoomKeys = {
 	KEY_RALT: 0x80 + 0x38,
 } as const;
 
-import { Key, matchesKey, parseKey } from "@voxcode/voxcode-tui";
+import { Key, matchesKey, parseKey } from "@voxcode-dev/voxcode-tui";
 
 /**
  * Map terminal key input to DOOM key codes

package/examples/extensions/doom-overlay/index.ts

@@ -9,7 +9,7 @@
  * This demonstrates that overlays can handle real-time game rendering at 35 FPS.
  */
 
-import type { ExtensionAPI } from "@voxcode/voxcode";
+import type { ExtensionAPI } from "@voxcode-dev/voxcode";
 import { DoomOverlayComponent } from "./doom-component.ts";
 import { DoomEngine } from "./doom-engine.ts";
 import { ensureWadFile } from "./wad-finder.ts";

package/examples/extensions/dynamic-resources/index.ts

@@ -1,6 +1,6 @@
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import type { ExtensionAPI } from "@voxcode/voxcode";
+import type { ExtensionAPI } from "@voxcode-dev/voxcode";
 
 const baseDir = dirname(fileURLToPath(import.meta.url));
 

package/examples/extensions/dynamic-tools.ts

@@ -7,7 +7,7 @@
  * - Registers additional tools at runtime via /add-echo-tool <name>
  */
 
-import type { ExtensionAPI } from "@voxcode/voxcode";
+import type { ExtensionAPI } from "@voxcode-dev/voxcode";
 import { Type } from "typebox";
 
 const ECHO_PARAMS = Type.Object({

package/examples/extensions/event-bus.ts

@@ -7,7 +7,7 @@
  * Usage: /emit [event-name] [data] - emit an event on the bus
  */
 
-import type { ExtensionAPI, ExtensionContext } from "@voxcode/voxcode";
+import type { ExtensionAPI, ExtensionContext } from "@voxcode-dev/voxcode";
 
 export default function (pi: ExtensionAPI) {
 	// Store ctx for use in event handler

package/examples/extensions/file-trigger.ts

@@ -9,7 +9,7 @@
  */
 
 import * as fs from "node:fs";
-import type { ExtensionAPI } from "@voxcode/voxcode";
+import type { ExtensionAPI } from "@voxcode-dev/voxcode";
 
 export default function (pi: ExtensionAPI) {
 	pi.on("session_start", async (_event, ctx) => {

package/examples/extensions/git-checkpoint.ts

@@ -5,7 +5,7 @@
  * When forking, offers to restore code to that point in history.
  */
 
-import type { ExtensionAPI } from "@voxcode/voxcode";
+import type { ExtensionAPI } from "@voxcode-dev/voxcode";
 
 export default function (pi: ExtensionAPI) {
 	const checkpoints = new Map<string, string>();

package/examples/extensions/github-issue-autocomplete.ts

@@ -1,13 +1,13 @@
 // Requires GitHub CLI (`gh`) and a GitHub repository checkout.
 // Preloads the latest open issues once per session, then filters them locally for fast `#...` completion.
 
-import type { ExtensionAPI } from "@voxcode/voxcode";
+import type { ExtensionAPI } from "@voxcode-dev/voxcode";
 import {
 	type AutocompleteItem,
 	type AutocompleteProvider,
 	type AutocompleteSuggestions,
 	fuzzyFilter,
-} from "@voxcode/voxcode-tui";
+} from "@voxcode-dev/voxcode-tui";
 
 type GitHubIssue = {
 	number: number;

package/examples/extensions/handoff.ts

@@ -12,10 +12,10 @@
  * The generated prompt appears as a draft in the editor for review/editing.
  */
 
-import type { ExtensionAPI, SessionEntry } from "@voxcode/voxcode";
-import { BorderedLoader, convertToLlm, serializeConversation } from "@voxcode/voxcode";
-import type { AgentMessage } from "@voxcode/voxcode-agent";
-import { complete, type Message } from "@voxcode/voxcode-ai";
+import type { ExtensionAPI, SessionEntry } from "@voxcode-dev/voxcode";
+import { BorderedLoader, convertToLlm, serializeConversation } from "@voxcode-dev/voxcode";
+import type { AgentMessage } from "@voxcode-dev/voxcode-agent";
+import { complete, type Message } from "@voxcode-dev/voxcode-ai";
 
 const SYSTEM_PROMPT = `You are a context transfer assistant. Given a conversation history and the user's goal for a new thread, generate a focused prompt that:
 

package/examples/extensions/hello.ts

@@ -2,8 +2,8 @@
  * Hello Tool - Minimal custom tool example
  */
 
-import { defineTool, type ExtensionAPI } from "@voxcode/voxcode";
-import { Type } from "@voxcode/voxcode-ai";
+import { defineTool, type ExtensionAPI } from "@voxcode-dev/voxcode";
+import { Type } from "@voxcode-dev/voxcode-ai";
 
 const helloTool = defineTool({
 	name: "hello",

package/examples/extensions/hidden-thinking-label.ts

@@ -18,7 +18,7 @@
  *   /thinking-label          Reset to the default label
  */
 
-import type { ExtensionAPI, ExtensionContext } from "@voxcode/voxcode";
+import type { ExtensionAPI, ExtensionContext } from "@voxcode-dev/voxcode";
 
 const DEFAULT_LABEL = "Pondering...";
 

package/examples/extensions/inline-bash.ts

@@ -14,7 +14,7 @@
  *
  * Note: Regular !command syntax (whole-line bash) is preserved and works as before.
  */
-import type { ExtensionAPI } from "@voxcode/voxcode";
+import type { ExtensionAPI } from "@voxcode-dev/voxcode";
 
 export default function (pi: ExtensionAPI) {
 	const PATTERN = /!\{([^}]+)\}/g;

package/examples/extensions/input-transform.ts

@@ -9,7 +9,7 @@
  *   ping                        → "pong" (instant, no LLM)
  *   time                        → current time (instant, no LLM)
  */
-import type { ExtensionAPI } from "@voxcode/voxcode";
+import type { ExtensionAPI } from "@voxcode-dev/voxcode";
 
 export default function (pi: ExtensionAPI) {
 	pi.on("input", async (event, ctx) => {

package/examples/extensions/interactive-shell.ts

@@ -21,7 +21,7 @@
  */
 
 import { spawnSync } from "node:child_process";
-import type { ExtensionAPI } from "@voxcode/voxcode";
+import type { ExtensionAPI } from "@voxcode-dev/voxcode";
 
 // Default interactive commands - editors, pagers, git ops, TUIs
 const DEFAULT_INTERACTIVE_COMMANDS = [

package/examples/extensions/mac-system-theme.ts

@@ -7,7 +7,7 @@
 
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
-import type { ExtensionAPI } from "@voxcode/voxcode";
+import type { ExtensionAPI } from "@voxcode-dev/voxcode";
 
 const execAsync = promisify(exec);