@poolzin/plcode 2.1.1

package/LICENSE

@@ -0,0 +1,23 @@
+
+
+MIT License
+
+Copyright (c) 2025 plcunha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# PLCODE
+
+<p align="center">
+  <strong>Terminal-first AI coding agent with multi-agent orchestration.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@poolzin/plcode"><img alt="npm" src="https://img.shields.io/npm/v/%40poolzin%2Fplcode?style=flat-square" /></a>
+  <a href="https://github.com/plcunha/PLCODE/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/plcunha/PLCODE/ci.yml?branch=main&style=flat-square" /></a>
+  <a href="https://github.com/plcunha/PLCODE/releases"><img alt="GitHub release" src="https://img.shields.io/github/v/release/plcunha/PLCODE?style=flat-square" /></a>
+  <a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/plcunha/PLCODE?style=flat-square" /></a>
+</p>
+
+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.
+- **Native binaries** — npm installs a small Node launcher and the correct compiled binary for the current platform.
+
+## Installation
+
+### npm (recommended)
+
+```bash
+npm install -g @poolzin/plcode
+plcode --version
+plcode doctor
+```
+
+Node.js 18 or newer is required only by the npm launcher. PLCODE itself runs as a compiled native binary; Bun is not required after installation.
+
+Optional dependencies must be enabled. If your package manager disables them, reinstall with:
+
+```bash
+npm install -g @poolzin/plcode --include=optional
+```
+
+### Install script
+
+Linux and macOS:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/plcunha/PLCODE/main/install | bash
+```
+
+Windows PowerShell:
+
+```powershell
+irm https://raw.githubusercontent.com/plcunha/PLCODE/main/install.ps1 | iex
+```
+
+### Supported binaries
+
+| Platform | Architectures | Notes                                                |
+| -------- | ------------- | ---------------------------------------------------- |
+| Linux    | x64, arm64    | glibc and musl; portable x64 baseline build included |
+| macOS    | x64, arm64    | Intel and Apple Silicon                              |
+| Windows  | x64           | Native executable                                    |
+
+## Quick start
+
+```bash
+# 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:
+
+```jsonc
+{
+  "$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:
+
+```text
+.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](docs/README.md)
+- [Getting started](docs/user/getting-started.md)
+- [Installation verification and repair](docs/user/installation-verification.md)
+- [MCP troubleshooting](docs/user/mcp-troubleshooting.md)
+- [Architecture](docs/developer/architecture.md)
+- [Testing](docs/developer/testing.md)
+- [Contributing](docs/developer/contributing.md)
+- [npm release process](docs/developer/npm-release.md)
+
+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.
+
+```bash
+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](docs/developer/testing.md) 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](https://github.com/plcunha/PLCODE/security/advisories/new).
+
+## 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](https://github.com/anomalyco/opencode) ecosystem and is distributed under the [MIT License](LICENSE).

package/bin/plcode

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+"use strict"
+
+// PLCODE npm launcher: resolves a compatible native package and inherits cwd.
+
+const fs = require("node:fs")
+const os = require("node:os")
+const path = require("node:path")
+const { execFileSync, spawnSync } = require("node:child_process")
+
+function fail(message) {
+  console.error(`plcode: ${message}`)
+  process.exit(1)
+}
+
+function run(target) {
+  const result = spawnSync(target, process.argv.slice(2), { stdio: "inherit" })
+  if (result.error) fail(result.error.message)
+  if (result.signal) {
+    try {
+      process.kill(process.pid, result.signal)
+    } catch {
+      process.exit(1)
+    }
+  }
+  process.exit(result.status ?? 1)
+}
+
+if (process.env.PLCODE_BIN_PATH) run(process.env.PLCODE_BIN_PATH)
+
+const platform = { darwin: "darwin", linux: "linux", win32: "windows" }[os.platform()]
+const arch = { x64: "x64", arm64: "arm64" }[os.arch()]
+if (!platform || !arch) fail(`unsupported platform: ${os.platform()}-${os.arch()}`)
+
+function isMusl() {
+  if (platform !== "linux") return false
+  try {
+    return !process.report?.getReport()?.header?.glibcVersionRuntime
+  } catch {
+    return false
+  }
+}
+
+function hasAvx2() {
+  if (arch !== "x64") return true
+  try {
+    if (platform === "linux") {
+      return /(?:^|\s)avx2(?:\s|$)/im.test(fs.readFileSync("/proc/cpuinfo", "utf8"))
+    }
+    if (platform === "darwin") {
+      const features = execFileSync("/usr/sbin/sysctl", ["-n", "machdep.cpu.leaf7_features"], {
+        encoding: "utf8",
+      })
+      return /(?:^|\s)AVX2(?:\s|$)/i.test(features)
+    }
+  } catch {
+    // Prefer the portable build when CPU capabilities cannot be determined.
+  }
+  return false
+}
+
+function packageCandidates() {
+  const base = `plcode-${platform}-${arch}`
+  const libc = platform === "linux" && isMusl() ? "-musl" : ""
+  if (arch === "x64") {
+    if (hasAvx2()) return [`${base}${libc}`, `${base}-baseline${libc}`]
+    return [`${base}-baseline${libc}`]
+  }
+  return [`${base}${libc}`]
+}
+
+const scriptDir = path.dirname(fs.realpathSync(__filename))
+const binaryName = platform === "windows" ? "plcode.exe" : "plcode"
+const candidates = packageCandidates()
+
+for (const packageName of candidates) {
+  try {
+    const manifest = require.resolve(`${packageName}/package.json`, { paths: [scriptDir] })
+    const binary = path.join(path.dirname(manifest), "bin", binaryName)
+    if (fs.existsSync(binary)) run(binary)
+  } catch {
+    // Try the next compatible package (for example the x64 baseline build).
+  }
+}
+
+fail(
+  `no compatible native package was installed for ${os.platform()}-${os.arch()}. ` +
+    `Expected one of: ${candidates.join(", ")}. ` +
+    `Reinstall with optional dependencies enabled: npm install -g plcode --include=optional`,
+)

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@poolzin/plcode",
+  "version": "2.1.1",
+  "description": "AI coding agent with multi-agent orchestration, 65 available agents, and a terminal-first workflow",
+  "license": "MIT",
+  "bin": {
+    "plcode": "bin/plcode"
+  },
+  "files": [
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/plcunha/PLCODE.git"
+  },
+  "homepage": "https://github.com/plcunha/PLCODE#readme",
+  "bugs": {
+    "url": "https://github.com/plcunha/PLCODE/issues"
+  },
+  "keywords": [
+    "ai",
+    "coding-agent",
+    "cli",
+    "terminal",
+    "multi-agent",
+    "developer-tools",
+    "llm",
+    "mcp"
+  ],
+  "optionalDependencies": {
+    "plcode-darwin-arm64": "2.1.1",
+    "plcode-darwin-x64": "2.1.1",
+    "plcode-darwin-x64-baseline": "2.1.1",
+    "plcode-linux-arm64": "2.1.1",
+    "plcode-linux-arm64-musl": "2.1.1",
+    "plcode-linux-x64": "2.1.1",
+    "plcode-linux-x64-baseline": "2.1.1",
+    "plcode-linux-x64-baseline-musl": "2.1.1",
+    "plcode-linux-x64-musl": "2.1.1",
+    "plcode-windows-x64": "2.1.1",
+    "plcode-windows-x64-baseline": "2.1.1"
+  }
+}