PLCODE

PLCODE is an open-source coding agent for interactive terminal work, headless automation, and structured multi-agent development. It combines a fast TUI with 65 available agents, 80 loaded skills, MCP/LSP/ACP support, project-level instructions, diagnostics, and provider-independent model access.

Why PLCODE?

• Terminal and headless workflows — use the TUI, plcode run, ACP, or the HTTP server.
• Specialized orchestration — delegate work to bundled agents and reusable skills instead of relying on one generic prompt.
• Provider-independent — configure OpenAI, Anthropic, Google, OpenRouter, local or OpenAI-compatible endpoints.
• Project-aware — load agents, skills, instructions, permissions, and MCP servers from .plcode/.
• Built for real repositories — Git integration, LSP, sessions, task tracking, statistics, and diagnostics.
• One npm package — the CLI, TUI worker, agents, skills, and instructions ship together in @poolzin/plcode.

Installation

Install Bun 1.3.14 or newer, then install the single npm package:

curl -fsSL https://bun.com/install | bash
npm install -g @poolzin/plcode
plcode --version
plcode doctor

PLCODE no longer publishes separate plcode-linux-*, plcode-darwin-*, or plcode-windows-* packages. Platform-specific runtime modules are provided only by third-party dependencies such as OpenTUI.

Quick start

# Interactive first-time setup
plcode init

# Authenticate a provider
plcode auth login

# Inspect available models
plcode models

# Start the TUI in the current repository
plcode

# Run a headless task
plcode run "Review this repository and fix the failing tests"

# Select a model explicitly
plcode --model openai/gpt-5.2

Run plcode --help or plcode <command> --help for the live command reference.

Core commands

| Command | Purpose | | ---------------------- | --------------------------------------- | | plcode [project] | Start the interactive TUI | | plcode run [message] | Execute a headless task | | plcode init | Run first-time setup | | plcode auth login | Configure provider credentials | | plcode models | List available models | | plcode doctor | Diagnose installation and configuration | | plcode agent list | List available agents | | plcode skill list | List available skills | | plcode session | Manage sessions | | plcode serve | Start the headless HTTP server | | plcode acp | Start the Agent Client Protocol server | | plcode stats | Show token usage and cost statistics | | plcode tools | Inspect available tools |

Configuration

PLCODE supports JSON and JSONC configuration. The usual locations are:

• project: .plcode/plcode.jsonc
• user: $XDG_CONFIG_HOME/plcode/plcode.jsonc
• Linux default user path: ~/.config/plcode/plcode.jsonc

Minimal project configuration:

{
  "$schema": "https://raw.githubusercontent.com/plcunha/PLCODE/main/packages/plcode/opencode/src/config/plcode.schema.json",
  "model": "openai/gpt-5.2",
  "permission": {
    "bash": "ask",
    "write": "ask",
  },
}

Project resources can be committed alongside the code:

.plcode/
├── AGENTS.md          # repository instructions
├── agent/             # custom agents
├── skill/             # reusable skills
├── instructions/      # additional instruction files
└── plcode.jsonc       # project configuration

Credentials should be added with plcode auth login, not committed to configuration files.

Documentation

• Documentation index
• Getting started
• Installation verification and repair
• MCP troubleshooting
• Architecture
• Testing
• Contributing
• npm release process

Historical implementation reports are kept under docs/archive/; they are not current user documentation.

Development

PLCODE uses Bun 1.3.14 and a Bun workspace.

git clone https://github.com/plcunha/PLCODE.git
cd PLCODE
bun install --frozen-lockfile

# Typecheck all workspaces (builds dependencies in the correct order)
bun run typecheck

# Full test suite
bun turbo test

# Run from source
bun run plcode

# Build a native binary for the current Linux x64 target
bun run plcode:build:target linux-x64

See the testing guide before submitting a pull request.

Security

• Review permission rules before enabling unattended execution.
• Keep provider credentials out of Git and use plcode auth login.
• Treat third-party plugins, skills, MCP servers, and shell commands as executable code.
• Report vulnerabilities privately through GitHub Security Advisories.

Project status

PLCODE is actively developed. CLI and configuration behavior may evolve between minor releases; release notes document material changes.

PLCODE builds on ideas and code from the open-source OpenCode ecosystem and is distributed under the MIT License.