CodePunk 0.1.0-alpha.16

CodePunk

Interactive AI-driven coding assistant for your terminal.

NOTE: This is a prerelease (alpha) build. APIs, commands, and provider support may change.

Install (Global Tool)

dotnet tool install --global CodePunk --prerelease
# Upgrade
dotnet tool update --global CodePunk --prerelease

Verify:

codepunk --version
codepunk --help

Quick Start

Launch interactive mode and run the guided setup:

codepunk
# inside interactive shell
a> /setup

The setup flow lets you:

1. Select an available provider (Anthropic for now)
2. Paste your API key (saved to a local auth.json with restricted permissions)
3. Choose a default model

Then start chatting:

> How do I refactor a large switch statement in C#?

At any time:

/providers    # list providers & defaults
/reload       # re-scan auth/config for newly added keys
/help         # show commands

Key Features

• Interactive chat with context persistence (SQLite-backed sessions)
• Tool calling (file read/write, shell execution) with iterative reasoning loop
• Provider abstraction (runtime registry, easily extensible)
• Rich terminal UI (Spectre.Console) with streaming responses
• JSON / quiet output modes for automation (many commands accept --json)

Commands (Selected)

Persistence

Files stored under ~/.config/codepunk/ (Linux/macOS) or %AppData%/CodePunk (Windows):

• auth.json : provider → API key (created via /setup or auth login)
• defaults.json : last chosen provider/model
• codepunk.db : session + planning data

Set CODEPUNK_CONFIG_HOME to override location.

Environment Variables (Optional)

export ANTHROPIC_API_KEY="your-key"
# (OpenAI temporarily disabled in this alpha)

If both a stored key and an env var exist, env var takes precedence on startup.

Logging & Verbosity

Enable additional logs + OTLP console tracing exporter:

export CODEPUNK_VERBOSE=1

Suppress decorative output for scripting:

export CODEPUNK_QUIET=1

Programmatic / JSON Usage

Many commands support --json to emit structured payloads with a schema discriminator. Example:

codepunk models --json | jq

Current Limitations (Alpha)

• OpenAI provider intentionally hidden pending updated implementation
• Basic error messages for some tool failures
• Planning workflow still evolving

Roadmap Highlights

• Re-enable OpenAI and add Azure OpenAI / local model backends
• Enhanced tool security sandbox & permission prompts
• Rich diff visualization for plan application
• Extensible plugin model for custom tools/providers

Contributing

Issues and PRs welcome: https://github.com/neil-gilbert/CodePunk

Local build:

git clone https://github.com/neil-gilbert/CodePunk.git
cd CodePunk
dotnet build
dotnet test

License

MIT

CodePunk – Ship faster with an AI pair inside your terminal.