VERSION=$(curl -fsSL https://api.github.com/repos/sazid/bitcode/releases/latest | grep '"tag_name"' | sed 's/.*"v\([^"]*\)".*/\1/')
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
curl -fsSL "https://github.com/sazid/bitcode/releases/download/v${VERSION}/bitcode-${VERSION}-${OS}-${ARCH}" -o bitcode
chmod +x bitcode

An agentic AI coding assistant in your terminal — with interactive TUI, smart security guards, extensible skills, built-in todo tracking with planning, and full control over reasoning effort.

• Interactive Mode — Full TUI with multiline input editor, bordered prompt, and keyboard shortcuts
• Single-Shot Mode — Run a single prompt from the command line with -p
• Agent Loop — Iterative LLM conversation with automatic tool calling (up to 50 turns)
• Tool Guards — Safety layer that validates tool calls before execution (rules-based, user prompts, or LLM-powered)
• Guard Agent — Expert multi-turn LLM agent for security-aware tool validation with language-specific skills
• System Reminders — Dynamic context injection via <system-reminder> tags with plugin support
• Skills — User-defined prompt templates loaded from .agents/, .claude/, or .bitcode/ directories
• Markdown Rendering — Rich terminal output with syntax-highlighted code blocks
• Reasoning Control — Adjustable reasoning effort (--reasoning flag)
• OpenRouter Integration — Works with any OpenAI-compatible API (including local servers)

• Go 1.26+
• An OpenRouter API key (or any OpenAI-compatible endpoint; not required for localhost)

Create a .env file in the project root with your API key:

OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxx

Optionally set the model and base URL:

OPENROUTER_MODEL=anthropic/claude-sonnet-4-20250514
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1

go build -o bitcode ./app

Interactive mode (default):

./bitcode

This launches a TUI with a multiline input editor. Use Ctrl+S to submit, Enter for newlines, Esc to clear, and Ctrl+D to exit.

Single-shot mode:

./bitcode -p "Your prompt here"

With reasoning effort:

./bitcode --reasoning high -p "Refactor the agent loop"

With a different model:

OPENROUTER_MODEL=anthropic/claude-sonnet-4-20250514 ./bitcode -p "Explain main.go"

With a local server (no API key needed):

OPENROUTER_BASE_URL=http://localhost:1234/v1 OPENROUTER_MODEL=local-model ./bitcode

Type these in the interactive prompt:

BitCode can inject dynamic context into the LLM conversation each turn using <system-reminder> tags. Reminders are evaluated before every API call and injected into a copy of the messages — the stored conversation history stays clean.

Built-in reminders handle skill availability and conversation length warnings. You can add your own by dropping plugin files into a reminders/ subdirectory:

# .bitcode/reminders/run-tests.yaml
id: run-tests
content: |
  Files were just edited. Consider running tests to verify the changes.
schedule:
  kind: condition
  condition: "after_tool:Edit,Write"
  max_fires: 5
priority: 3

Plugins are loaded from {.agents,.claude,.bitcode}/reminders/ at both the user home and project level. See docs/system-reminders.md for the full architecture, schedule kinds, condition expressions, and more examples.

BitCode includes a safety layer that validates tool calls before execution. The guard system can:

• Allow — Proceed with tool execution
• Deny — Block the tool call with an error
• Ask — Prompt the user for approval
• LLM Guard — Use a secondary LLM to evaluate the tool call

The Guard Agent is an expert multi-turn LLM agent specifically designed for security-aware tool validation. It:

• Uses a security/sysadmin persona system prompt
• Automatically injects language-specific security skills (Bash, Python, Go, JavaScript) based on detected environment
• Supports on-demand "simulate" skill for step-by-step code tracing
• Can escalate to user prompts when uncertain

The guard agent is enabled by default. Set BITCODE_GUARD_LLM=false to use only rule-based guards.

See docs/tool-guards.md for the full architecture, rule definitions, and customization options.

BitCode includes a built-in task management system accessible via tools:

• TodoWrite — Create and manage a structured task list for the current session
• TodoRead — Read the current todo list

Each task has an id, content, status (pending, in_progress, completed), and priority (high, medium, low). The agent automatically tracks progress and updates the todo list as tasks are completed.

See docs/todo.md for detailed usage patterns and best practices.

app/
  main.go           # Entry point, CLI flags, interactive REPL loop
  agent.go          # Agent loop (LLM ↔ tool call cycle)
  input.go          # TUI input editor (bubbletea textarea)
  render.go         # Terminal rendering (markdown, spinner, events)
  system_prompt.go  # System prompt construction
internal/
  event.go          # Event types for tool output
  llm/
    llm.go          # Provider interface, message types, content blocks
    openai.go       # OpenAI-compatible provider (sync + streaming)
  guard/            # Tool guard system (rules, LLM validator, guard agent)
    skills/         # Guard agent security skills (bash, python, go, js, simulate)
  reminder/         # System reminder framework (evaluation, injection, plugins)
  skills/           # Skill discovery and management
  tools/            # Tool implementations (read, write, edit, glob, bash, todo)
docs/
  tool-guards.md    # Tool guard architecture and customization
  todo.md           # Todo system usage guide
  system-reminders.md  # System reminders architecture and plugin guide

See LICENSE for the full license text.