Lightcode

A lightweight terminal coding agent written in Go

What is Lightcode?

Lightcode is a terminal-based coding agent for developers. It connects to any OpenAI-compatible model provider.

Features

• OpenAI-compatible — works with any provider that speaks the OpenAI Chat Completions API (OpenAI, Anthropic via proxy, Ollama, LM Studio, etc.)
• OAuth providers — sign in from the TUI with Codex ChatGPT auth or GitHub Copilot device login
• Low memory usage — uses less ram around 20-30 mb
• Skills — uses specialized agent-skills.
• Multi-model support — configure multiple providers and switch between models with /models inside the TUI

Requirements

• Go 1.25+
• At least one OpenAI-compatible endpoint configured

Install

Prerequisites

Before installing, make sure the required system dependencies are present. Run the following on:

1. Debian/Ubuntu-based systems:

sudo apt install libx11-dev libxext-dev libxi-dev libsqlite3-dev

1. Fedora/RHEL/CentOS (dnf/yum):

sudo dnf install libX11-devel libXext-devel libXi-devel sqlite-devel

1. Arch Linux / Manjaro (pacman)

sudo pacman -S libx11 libxext libxi sqlite

1. openSUSE (zypper):

sudo zypper install libX11-devel libXext-devel libXi-devel sqlite3-devel

Note: These libraries are required for native display and database support. Installation will fail without them.

Final Installation

go install github.com/Kartik-2239/lightcode/cmd/lightcode@latest

Quick Start

Run the TUI and API server together (defaults to :8080):

lightcode

Or run directly from source:

go run ./cmd/lightcode/main.go

On first run, Lightcode creates ~/.lightcode/ with a default config.json. If no provider is configured yet, the TUI still opens and prompts you to run /login.

TUI commands

Codex OAuth

Lightcode can use your existing Codex ChatGPT login instead of an OpenAI API key.

1. Sign in with the Codex CLI:

codex login

1. Make sure Codex is using file-based credential storage if your machine does not have ~/.codex/auth.json:

# ~/.codex/config.toml
cli_auth_credentials_store = "file"

1. Start Lightcode and select Codex during onboarding, or run /login in the TUI and choose codex to launch codex login. After login, open /models and choose a model from the codex auth provider.

Use /effort with Codex auth models to set reasoning effort: low, medium, high, or extra high (xhigh on the wire).

Lightcode imports ChatGPT OAuth tokens from ${CODEX_HOME:-~/.codex}/auth.json into ~/.lightcode/auth.json under the codex provider. Treat both files like passwords and do not commit or share them.

If a request fails with token_invalidated or refresh_token_invalidated, run /login and choose codex again. Lightcode clears its imported Codex token, runs codex logout, launches a fresh codex login, and re-imports the refreshed auth cache.

GitHub Copilot OAuth

Run /login in the TUI and choose copilot to start GitHub's device login flow. Lightcode opens https://github.com/login/device, shows the user code in the chat, polls until GitHub accepts the authorization, then saves the access token under the copilot provider.

After login, open /models and choose a model from the copilot auth provider. Lightcode shows the same picker labels used by Copilot and maps them to the underlying model IDs internally:

• Auto
• GPT-5.4 mini (default)
• GPT-5 mini
• Claude Haiku 4.5
• Gemini 3.1 Pro (Preview)

Run /logout and choose copilot to remove the saved token and any selected Copilot model.

Copilot OAuth uses GitHub's documented device flow. Copilot model access uses GitHub Copilot service endpoints and can change outside Lightcode's control. Treat ~/.lightcode/auth.json like a password and do not commit or share it.

Configuration

All settings live under ~/.lightcode/config.json. The file is created automatically on first run.

Full example

{
  "theme": "light",
  "skills_path": "~/.lightcode/skills",
  "port": "8080",
  "providers": [
    {
      "models": ["gpt-5.5"],
      "base_url": "https://api.openai.com/v1",
      "api_key": "sk-..."
    },
    {
      "models": ["some-ai-800b"],
      "base_url": "https://your-gateway.example/v1",
      "api_key": "your-api-key"
    }
  ]
}

OAuth models are stored separately in ~/.lightcode/auth.json:

{
  "codex": {
    "type": "oauth",
    "access_token": "...",
    "refresh_token": "...",
    "expires": 2000000000,
    "account_id": "...",
    "models": ["gpt-5.5", "gpt-5.4-mini", "gpt-5.3-codex-spark"]
  },
  "copilot": {
    "type": "oauth",
    "access_token": "...",
    "refresh_token": "",
    "expires": 0,
    "account_id": "",
    "models": ["Auto", "GPT-5.4 mini (default)", "GPT-5 mini", "Claude Haiku 4.5", "Gemini 3.1 Pro (Preview)"]
  }
}

Config reference

Providers

Each entry in the providers array requires:

Once configured, run /models inside the TUI to select your active model.

Skills

Skills give the agent domain-specific context and significantly improve response quality for specialized tasks.

To add a skill:

1. Create a subdirectory under ~/.lightcode/skills/
2. Add a SKILL.md file inside it describing the context or instructions

~/.lightcode/skills/
├── golang/
│   └── SKILL.md
└── docker/
    └── SKILL.md

You can also point skills_path in config.json to any other directory on your system.