copilot

A CLI agent that runs LLM-powered tool-use loops against OpenAI-compatible APIs.

Overview

copilot sends a prompt to a configured LLM, which can then call registered actions (file reading, directory listing, shell commands). The agent loops—feeding action results back to the model—until the LLM produces a final text response with no more tool calls.

Usage

copilot [options] <model> <prompt>

Options

Flag	Description
-c, --config <path>	Path to actions config (default: config/actions.yaml)
--models <path>	Path to model definitions config (default: config/models.yaml)
--base-url <url>	Override API base URL
--api-key <key>	Override API key
--system <prompt>	System prompt
--max-tokens <n>	Max output tokens (default: 4096)
--chat-completions-api	Force Chat Completions API
--responses-api	Force Responses API (default)
-v	Verbose logging
--trace	Trace agent loop steps to stderr

Examples

# Use a model defined in config/models.yaml
copilot deepseek-v3 "What files are in the current directory?"

# Use a custom base URL directly
copilot --base-url http://localhost:8000/v1 --api-key sk-... qwen3.6 "Summarize this repo"

# With a system prompt and verbose output
copilot -v --system "You are a helpful coding assistant." deepseek-v3 "Explain the project structure"

Configuration

Models (config/models.yaml)

Defines named model endpoints. Supports ${ENV_VAR} expansion for API keys.

models:
  deepseek-v3:
    kind: chat              # "chat" or "responses"
    model: deepseek-v3
    base_url: https://api.deepseek.com/v1
    api_key: sk-...

• kind: chat — uses the Chat Completions API (works with most providers)
• kind: responses — uses the OpenAI Responses API

Actions (config/actions.yaml)

Defines the tools available to the agent. Each action has a name, description, and JSON Schema for its input.

Three built-in actions are registered in code:

• read_file — read a file's contents
• list_directory — list entries in a directory
• shell_exec — execute a shell command

Architecture

cmd/copilot/main.go          CLI entrypoint, argument parsing
internal/
  agent/agent.go              Agent loop: send prompt, dispatch intents, repeat
  action/
    action.go                 Action interface and ActionResult type
    registry.go               Registry mapping names to definitions + handlers
    config.go                 YAML config loader
    code/                     Built-in action implementations
  model/
    model.go                  Model config loader with env var expansion
  oai/
    chat.go                   OpenAI Chat Completions API adapter
    responses.go              OpenAI Responses API adapter

Building

go build -o bin/copilot ./cmd/copilot

Testing

go test ./...