AI-powered coding assistant CLI
npm install portercodeAI-powered coding assistant CLI.
``bash`
npm install -g portercode
Requirements: Bun runtime
`bashInteractive mode
porter
Commands
porter Start interactive TUI
porter auth Manage API credentials
porter config Show configuration
Options
| Option | Description |
|--------|-------------|
|
| Enable debug mode |
| -s, --session | Continue specific session |
| -c, --continue | Continue most recent session |
| -m, --model | Model to use (provider/model) |
| --port | Start HTTP server on specified port (for VS Code extension) |---
VS Code Extension Communication
When started with
--port, PorterCode runs an HTTP server for communication with the VS Code extension.$3
- HTTP REST API: For requests (prompts, sessions, auth, permissions)
- SSE (Server-Sent Events): For real-time streaming responses
$3
| Endpoint | Method | Description |
|----------|--------|-------------|
|
/health | GET | Health check |
| /events | GET | SSE stream for real-time events |
| /api/sessions | GET | List all sessions |
| /api/sessions | POST | Create a new session |
| /api/sessions/:id/messages | GET | Get messages for a session |
| /api/prompt | POST | Send a prompt to the LLM |
| /api/cancel | POST | Cancel active generation |
| /api/permission | POST | Respond to permission requests |
| /api/auth/status | GET | Check authentication status |
| /api/auth/providers | GET | List available LLM providers |
| /api/auth/credentials | POST | Save API key credential |$3
The
/events endpoint streams the following event types:| Event | Description |
|-------|-------------|
|
heartbeat | Keep-alive ping |
| message.start | LLM generation started |
| message.delta | Text content chunk |
| reasoning.delta | Reasoning/thinking content chunk |
| message.complete | LLM generation finished |
| tool.start | Tool execution started |
| tool.complete | Tool execution finished |
| permission.request | Permission required for tool |
| session.updated | Session metadata changed |$3
`javascript
const eventSource = new EventSource('http://localhost:50123/events');eventSource.addEventListener('message.delta', (e) => {
const data = JSON.parse(e.data);
console.log('Content:', data.content);
});
eventSource.addEventListener('tool.start', (e) => {
const data = JSON.parse(e.data);
console.log('Tool:', data.toolName);
});
`---
Publishing
PorterCode uses a unified publish workflow that handles both GitHub Releases (standalone executables) and npm publishing.
$3
1. GitHub CLI:
installed and authenticated (gh auth login)
2. npm account: With publish access and 2FA enabled
3. Bun: Runtime installed$3
`bash
Publish everywhere (GitHub Releases + npm)
bun run publish --version 0.1.11Preview without publishing
bun run publish --version 0.1.11 --dry-run
`$3
| Command | Description |
|---------|-------------|
|
| Publish to GitHub Releases and npm |
| bun run publish --version X.Y.Z --github | Only GitHub Releases (standalone executables) |
| bun run publish --version X.Y.Z --npm | Only npm registry |
| bun run publish --version X.Y.Z --dry-run | Preview changes without publishing |$3
#### GitHub Releases (
--github)Standalone executables uploaded to portercode-releases:
| Platform | File |
|----------|------|
| Windows x64 |
porter-windows-x64.exe |
| Linux x64 | porter-linux-x64 |
| macOS Intel | porter-macos-x64 |
| macOS Apple Silicon | porter-macos-arm64 |Plus install scripts:
install-windows.bat, install.sh#### npm Registry (
)Obfuscated JavaScript package:
-
dist/index.js - Compiled and obfuscated code
- dist/*/.d.ts - Type declarations
- LICENSE, NOTICE, package.jsonSource code (
) is NOT published to npm.$3
The unified publish command performs these steps:
1. [1/4] Update version - Updates
package.json with the new version
2. [2/4] Build executables - Compiles standalone binaries for all platforms (GitHub only)
3. [3/4] GitHub Release - Creates release and uploads executables
4. [4/4] npm Publish - Runs npm login (for OTP) then publishes$3
If you need more control, use individual scripts:
`bash
Build standalone executables only
bun run build-all-platforms.tsUpload to GitHub Releases only
bun run release.ts
bun run release.ts --draft # Create as draftBuild npm package only
bun run build
`$3
bash
Check npm
npm info portercodeTest installation
npm install -g portercode
porter --versionCheck GitHub release
gh release view v0.1.11 --repo portermetrics/portercode-releases
`$3
bash
npm: Unpublish within 72 hours
npm unpublish portercode@0.1.11npm: Deprecate (after 72 hours)
npm deprecate portercode@0.1.11 "Critical bug, use 0.1.12"GitHub: Delete release
gh release delete v0.1.11 --repo portermetrics/portercode-releases --yes
`---
Features
- 🤖 Multi-LLM Support: Works with Anthropic Claude, OpenAI GPT, Google Gemini, and Groq
- 🔐 Granular Permissions: Fine-grained control over file operations and command execution
- 💬 Interactive Sessions: Save and resume conversations
- ⚙️ Configurable: Hierarchical configuration system with JSONC support
- 🔧 Extensible Tools: Read, write, edit files, execute commands, search code
- 🎨 Terminal UI: Beautiful interactive interface built with Ink
- 📡 VS Code Integration: HTTP + SSE server for VS Code extension
Development
bash
Run in dev mode
bun run devRun tests
bun testType check
bun run typecheck
`---
Configuration
Create a
file in your project root or ~/.config/portercode/porter.jsonc globally:`jsonc
{
"model": "claude-sonnet-4",
"permission": {
"edit": "ask", // Always ask before editing files
"bash": "auto" // Execute commands automatically
}
}
`$3
| Option | Description | Values |
|--------|-------------|--------|
|
| Default LLM model | claude-sonnet-4, gpt-4, gemini-pro, etc. |
| permission.edit | Permission for editing files | ask, auto, deny |
| permission.write | Permission for creating files | ask, auto, deny |
| permission.bash | Permission for shell commands | ask, auto, deny` |---
Proprietary - See LICENSE for details.
Copyright (c) 2025 Carlos Alexis Gomez Ruiz. All rights reserved.