@voxcode-dev/voxcode 0.1.0

package/docs/development.md

@@ -0,0 +1,28 @@
+# Development
+
+## Prerequisites
+
+- Node.js 20+
+- npm 10+
+
+## Setup
+
+```bash
+npm install --ignore-scripts
+npm run check
+```
+
+## Build
+
+```bash
+npm run build
+```
+
+## Test and Validation
+
+```bash
+npm run test
+npm run check
+```
+
+Read contribution rules in `../../../CONTRIBUTING.md`.

package/docs/docs.json

@@ -0,0 +1,45 @@
+{
+  "title": "Voxcode Documentation",
+  "project": "Voxcode",
+  "baseUrl": "https://voxcode.dev",
+  "navigation": [
+    {
+      "title": "Start Here",
+      "items": [
+        { "title": "Overview", "path": "index.md" },
+        { "title": "Quickstart", "path": "quickstart.md" },
+        { "title": "Usage", "path": "usage.md" },
+        { "title": "Providers", "path": "providers.md" },
+        { "title": "Settings", "path": "settings.md" }
+      ]
+    },
+    {
+      "title": "Core",
+      "items": [
+        { "title": "Models", "path": "models.md" },
+        { "title": "Sessions", "path": "sessions.md" },
+        { "title": "Compaction", "path": "compaction.md" },
+        { "title": "Skills", "path": "skills.md" },
+        { "title": "Extensions", "path": "extensions.md" }
+      ]
+    },
+    {
+      "title": "Interfaces",
+      "items": [
+        { "title": "TUI", "path": "tui.md" },
+        { "title": "SDK", "path": "sdk.md" },
+        { "title": "RPC", "path": "rpc.md" },
+        { "title": "JSON", "path": "json.md" }
+      ]
+    },
+    {
+      "title": "Platform",
+      "items": [
+        { "title": "Windows", "path": "windows.md" },
+        { "title": "Termux", "path": "termux.md" },
+        { "title": "tmux", "path": "tmux.md" },
+        { "title": "Terminal Setup", "path": "terminal-setup.md" }
+      ]
+    }
+  ]
+}

package/docs/extensions.md

@@ -0,0 +1,18 @@
+# Extensions
+
+Extensions let you add custom behavior to Voxcode.
+
+## What You Can Extend
+
+- Tool integrations
+- Provider adapters
+- Workflow hooks
+- Command surfaces
+
+## Design Guidance
+
+- Keep extensions focused and composable.
+- Validate inputs/outputs explicitly.
+- Document side effects and permissions.
+
+See also [custom-provider.md](custom-provider.md).

package/docs/index.md

@@ -0,0 +1,34 @@
+# Voxcode Documentation
+
+Welcome to Voxcode docs.
+
+## Start Here
+
+- [Quickstart](quickstart.md)
+- [Usage](usage.md)
+- [Providers](providers.md)
+- [Models](models.md)
+- [Settings](settings.md)
+
+## Core Concepts
+
+- [Sessions](sessions.md)
+- [Compaction](compaction.md)
+- [Skills](skills.md)
+- [Extensions](extensions.md)
+
+## Programmatic Interfaces
+
+- [SDK](sdk.md)
+- [RPC](rpc.md)
+- [JSON Mode](json.md)
+- [TUI](tui.md)
+
+## Platform and Setup
+
+- [Windows](windows.md)
+- [Termux](termux.md)
+- [tmux](tmux.md)
+- [Terminal Setup](terminal-setup.md)
+
+For project updates and release notes, see https://voxcode.dev.

package/docs/json.md

@@ -0,0 +1,15 @@
+# JSON Mode
+
+JSON mode emits structured output for scripting and automation.
+
+## Why Use It
+
+- Reliable machine parsing
+- Stable downstream integrations
+- Better CI and pipeline compatibility
+
+## Example
+
+```bash
+voxcode --json -p "List changed files and summarize impact"
+```

package/docs/keybindings.md

@@ -0,0 +1,12 @@
+# Keybindings
+
+## Core Navigation
+
+- `Ctrl+C`: cancel current operation
+- `Enter`: submit input
+- `Up/Down`: browse history
+- `Tab`: cycle context options
+
+## Notes
+
+Exact behavior can vary by terminal and platform. See [terminal-setup.md](terminal-setup.md) for compatibility tips.

package/docs/models.md

@@ -0,0 +1,19 @@
+# Models
+
+## Choosing a Model
+
+Pick based on task type:
+
+- Fast iteration: smaller, lower-latency models
+- Complex reasoning: higher-capability models
+- Budget-sensitive runs: lower-cost models with strict prompts
+
+## Practical Strategy
+
+1. Use a fast default model for routine coding tasks.
+2. Switch to a stronger model for architecture, debugging, or refactors.
+3. Pin model versions for reproducible automation.
+
+## Where to Configure
+
+Configure model defaults in your Voxcode settings and/or per command.

package/docs/packages.md

@@ -0,0 +1,8 @@
+# Package Structure
+
+Monorepo package overview:
+
+- `packages/voxcode`: CLI and product-facing runtime
+- `packages/voxcode-ai`: provider and model integrations
+- `packages/voxcode-agent`: agent core loop and orchestration
+- `packages/voxcode-tui`: terminal UI primitives

package/docs/prompt-templates.md

@@ -0,0 +1,16 @@
+# Prompt Templates
+
+Prompt templates let teams standardize high-value workflows.
+
+## Good Template Traits
+
+- Clear task goal
+- Explicit constraints
+- Required output format
+- Verification steps
+
+## Examples
+
+- Bug triage template
+- Refactor plan template
+- Release-note generation template

package/docs/providers.md

@@ -0,0 +1,21 @@
+# Providers
+
+Voxcode supports multiple model providers.
+
+## Common Providers
+
+- OpenAI
+- Anthropic
+- Google Gemini
+- Mistral
+- Amazon Bedrock
+- Azure OpenAI
+- Groq
+- OpenRouter
+- Together AI
+
+## Setup Pattern
+
+Set provider API keys as environment variables, then select model/provider in settings.
+
+See [settings.md](settings.md) and [models.md](models.md).

package/docs/quickstart.md

@@ -0,0 +1,29 @@
+# Quickstart
+
+## Install
+
+```bash
+npm i -g voxcode
+```
+
+## Configure a Provider Key
+
+```bash
+export ANTHROPIC_API_KEY="your-key"
+```
+
+You can also use OpenAI, Google, Mistral, Bedrock, and others.
+
+## Run Voxcode
+
+```bash
+voxcode
+```
+
+## First Prompt
+
+```text
+Summarize this repository and suggest three improvements.
+```
+
+Next: [usage.md](usage.md)

package/docs/rpc.md

@@ -0,0 +1,15 @@
+# RPC Mode
+
+RPC mode is designed for process-to-process integrations.
+
+## Use Cases
+
+- IDE integrations
+- Supervisor services
+- Local orchestrators
+
+## Behavior
+
+- Structured request/response boundaries
+- Deterministic payload handling
+- Integration-friendly transport patterns

package/docs/sdk.md

@@ -0,0 +1,12 @@
+# SDK
+
+The Voxcode SDK enables embedding agent workflows into your own Node.js or TypeScript applications.
+
+## Typical Use Cases
+
+- Internal automation tools
+- CI assistant workflows
+- Custom developer portals
+- Programmatic session orchestration
+
+See package-level APIs in `../README.md` and source docs.

package/docs/session-format.md

@@ -0,0 +1,12 @@
+# Session File Format
+
+Session files store serialized conversation and runtime metadata.
+
+## Contents
+
+- Message timeline
+- Tool execution events
+- Session metadata and timestamps
+- Compaction summaries
+
+Treat session files as sensitive project artifacts when they contain private code or prompts.

package/docs/sessions.md

@@ -0,0 +1,17 @@
+# Sessions
+
+Sessions capture conversation history, context, and execution state.
+
+## What Sessions Enable
+
+- Continue work across terminal restarts
+- Branch and compare approaches
+- Keep iterative coding loops coherent
+
+## Session Workflow
+
+1. Start a session in interactive mode.
+2. Resume by selecting a prior session.
+3. Compact when history gets too large.
+
+See [session-format.md](session-format.md) and [compaction.md](compaction.md).

package/docs/settings.md

@@ -0,0 +1,15 @@
+# Settings
+
+Voxcode settings control runtime behavior, providers, model defaults, UI, and safety features.
+
+## Common Categories
+
+- Provider credentials and defaults
+- Model routing and fallback
+- Session and history behavior
+- TUI preferences
+- Telemetry and offline controls
+
+## Recommendation
+
+Keep team defaults minimal, and override per-user where needed.

package/docs/shell-aliases.md

@@ -0,0 +1,10 @@
+# Shell Aliases
+
+Useful aliases for daily workflows:
+
+```bash
+alias vx='voxcode'
+alias vxp='voxcode -p'
+```
+
+Adjust aliases to match your shell and team conventions.

package/docs/skills.md

@@ -0,0 +1,18 @@
+# Skills
+
+Skills are reusable instruction packs for common workflows.
+
+## Why Skills
+
+- Standardize repeated tasks
+- Reduce prompt boilerplate
+- Improve consistency across contributors
+
+## Typical Uses
+
+- Debugging workflows
+- Documentation generation
+- Refactor procedures
+- Release and verification checklists
+
+Skills can be project-local or shared across teams.

package/docs/terminal-setup.md

@@ -0,0 +1,15 @@
+# Terminal Setup
+
+## Recommended
+
+- UTF-8 locale
+- True color support
+- Stable monospace font
+
+## Verify
+
+- Input latency is low
+- Keybindings are recognized
+- Colors are readable for diagnostics
+
+If behavior is inconsistent, test in an alternative terminal emulator.

package/docs/termux.md

@@ -0,0 +1,9 @@
+# Termux / Android Support
+
+Voxcode can run in Termux with the proper Node.js environment.
+
+## Setup Notes
+
+- Install current Node.js and npm packages
+- Validate terminal color and keyboard behavior
+- Keep prompts concise for mobile workflows

package/docs/themes.md

@@ -0,0 +1,13 @@
+# Themes
+
+Themes control colors and readability in the interactive TUI.
+
+## Theme Guidelines
+
+- Ensure high contrast for code and diagnostics.
+- Prefer stable palettes across light and dark terminals.
+- Keep semantic colors consistent (error, warning, success, info).
+
+## Team Tip
+
+Standardize one default theme in team onboarding docs.

package/docs/tmux.md

@@ -0,0 +1,9 @@
+# tmux Integration
+
+Voxcode works well in tmux for persistent development sessions.
+
+## Tips
+
+- Use separate panes for agent output and test commands.
+- Enable mouse mode only if your workflow needs it.
+- Keep scrollback large enough for debugging transcripts.

package/docs/tui.md

@@ -0,0 +1,12 @@
+# TUI
+
+The Voxcode TUI is the interactive terminal interface for real-time agent workflows.
+
+## Capabilities
+
+- Live streaming responses
+- Tool execution feedback
+- Session navigation
+- Keyboard-first controls
+
+For setup and terminal compatibility, see [terminal-setup.md](terminal-setup.md).

package/docs/usage.md

@@ -0,0 +1,19 @@
+# Usage Guide
+
+## Interactive
+
+```bash
+voxcode
+```
+
+Use interactive mode for exploratory coding, debugging, and iterative tasks.
+
+## One-Shot Prompt
+
+```bash
+voxcode -p "Write tests for src/parser.ts"
+```
+
+## Automation
+
+Use JSON or RPC mode for integration into scripts and tools.

package/docs/windows.md

@@ -0,0 +1,11 @@
+# Windows Support
+
+Voxcode supports Windows environments.
+
+## Recommendations
+
+- Use modern PowerShell
+- Keep Node.js and npm updated
+- Prefer terminals with solid ANSI support
+
+If needed, use WSL for Linux-like toolchains.

package/examples/README.md

@@ -0,0 +1,25 @@
+# Examples
+
+Example code for pi-coding-agent SDK and extensions.
+
+## Directories
+
+### [sdk/](sdk/)
+Programmatic usage via `createAgentSession()`. Shows how to customize models, prompts, tools, extensions, and session management.
+
+### [extensions/](extensions/)
+Example extensions demonstrating:
+- Lifecycle event handlers (tool interception, safety gates, context modifications)
+- Custom tools (todo lists, questions, subagents, output truncation)
+- Commands and keyboard shortcuts
+- Custom UI (footers, headers, editors, overlays)
+- Git integration (checkpoints, auto-commit)
+- System prompt modifications and custom compaction
+- External integrations (SSH, file watchers, system theme sync)
+- Custom providers (Anthropic with custom streaming, GitLab Duo)
+
+## Documentation
+
+- [SDK Reference](sdk/README.md)
+- [Extensions Documentation](../docs/extensions.md)
+- [Skills Documentation](../docs/skills.md)