{"_id":"@aadithya2112/pcode","_rev":"6-ed32f1afc79e9ef4912986891e22ec6f","name":"@aadithya2112/pcode","dist-tags":{"latest":"1.0.5"},"versions":{"1.0.0":{"name":"@aadithya2112/pcode","version":"1.0.0","keywords":["cli","ai","coding-agent","claude","automation"],"author":{"name":"aadithya2112"},"license":"MIT","_id":"@aadithya2112/pcode@1.0.0","maintainers":[{"name":"aadithya2112","email":"aadithyacps@gmail.com"}],"homepage":"https://github.com/aadithya2112/coding-agent-cli#readme","bugs":{"url":"https://github.com/aadithya2112/coding-agent-cli/issues"},"bin":{"pcode":"src/cli.ts"},"dist":{"shasum":"e71d9abf1c3839073bedc469645a57aed0b7e610","tarball":"https://registry.npmjs.org/@aadithya2112/pcode/-/pcode-1.0.0.tgz","fileCount":12,"integrity":"sha512-SLuCLp7CF2gp6PpNn7Xq9p/b2jDAA5svvfIyDwkaaft1SMVJ4tckQny/GczdH/JvF8+9uOkkWZcObyHCbksL5g==","signatures":[{"sig":"MEQCIDGB7SB6CyZzNBwQWMhHTfGKooRmkMo0v7wY6gp3VNpdAiBDrPw7rRKBr4WzRoaZrMiUYYwv0+NqcyU/nmXYlnASdQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":44105},"type":"module","module":"index.ts","engines":{"bun":">=1.0.0"},"scripts":{"cli":"bun run src/cli.ts","dev":"bun run src/cli.ts --interactive","scenario":"bun run scripts/scenario.ts"},"_npmUser":{"name":"aadithya2112","email":"aadithyacps@gmail.com"},"repository":{"url":"git+https://github.com/aadithya2112/coding-agent-cli.git","type":"git"},"_npmVersion":"11.4.2","description":"A coding agent CLI powered by Claude","directories":{},"_nodeVersion":"22.12.0","_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/pcode_1.0.0_1764942340909_0.56314088231713","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@aadithya2112/pcode","version":"1.0.1","keywords":["cli","ai","coding-agent","claude","automation"],"author":{"name":"aadithya2112"},"license":"MIT","_id":"@aadithya2112/pcode@1.0.1","maintainers":[{"name":"aadithya2112","email":"aadithyacps@gmail.com"}],"homepage":"https://github.com/aadithya2112/coding-agent-cli#readme","bugs":{"url":"https://github.com/aadithya2112/coding-agent-cli/issues"},"bin":{"pcode":"src/cli.ts"},"dist":{"shasum":"0ce0d675559f302b8075f5dd7a2e5d75881fd122","tarball":"https://registry.npmjs.org/@aadithya2112/pcode/-/pcode-1.0.1.tgz","fileCount":12,"integrity":"sha512-NoCEQjdKMOwLgPGT3xFYtupCr0fq6s/5tVAa5x2R1jaKBp5/rvXduYAp7KJAmXyzRjguFoQEU7c++5X0ZcdGRw==","signatures":[{"sig":"MEUCIQDXEfm+Fa++uffwrnVzMCc63+tPV21SgJqtF9wM4aPqagIgPIh2ciyr8UrDZOdnVQm9iFHnEhx7p9jCISdUU9qEgjw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":45600},"type":"module","module":"index.ts","engines":{"bun":">=1.0.0"},"scripts":{"cli":"bun run src/cli.ts","dev":"bun run src/cli.ts --interactive","scenario":"bun run scripts/scenario.ts"},"_npmUser":{"name":"aadithya2112","email":"aadithyacps@gmail.com"},"repository":{"url":"git+https://github.com/aadithya2112/coding-agent-cli.git","type":"git"},"_npmVersion":"11.4.2","description":"A coding agent CLI powered by Claude","directories":{},"_nodeVersion":"22.12.0","_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/pcode_1.0.1_1764942624982_0.8371109732997566","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@aadithya2112/pcode","version":"1.0.2","keywords":["cli","ai","coding-agent","claude","automation"],"author":{"name":"aadithya2112"},"license":"MIT","_id":"@aadithya2112/pcode@1.0.2","maintainers":[{"name":"aadithya2112","email":"aadithyacps@gmail.com"}],"homepage":"https://github.com/aadithya2112/coding-agent-cli#readme","bugs":{"url":"https://github.com/aadithya2112/coding-agent-cli/issues"},"bin":{"pcode":"src/cli.ts"},"dist":{"shasum":"36d7897b0ad428702d14c3b741ff10e7ce56c898","tarball":"https://registry.npmjs.org/@aadithya2112/pcode/-/pcode-1.0.2.tgz","fileCount":12,"integrity":"sha512-zpJppTDuqsqTJIX6dQB5uoJu6MnmBgWdswderJQRhZzoy75kvqGhU2xTY7lABaseyQ31iB6ezTgJ3dFi/gzV2w==","signatures":[{"sig":"MEYCIQDlLqd0CgMBMB+1k2PjKRxVzkjonofPieFv+qP3s2Z9BQIhAO4o43eO0tk0QSYRNBKDAu0wZUTA2Q283F1csG7o6lPh","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":46283},"type":"module","module":"index.ts","engines":{"bun":">=1.0.0"},"scripts":{"cli":"bun run src/cli.ts","dev":"bun run src/cli.ts --interactive","scenario":"bun run scripts/scenario.ts"},"_npmUser":{"name":"aadithya2112","email":"aadithyacps@gmail.com"},"repository":{"url":"git+https://github.com/aadithya2112/coding-agent-cli.git","type":"git"},"_npmVersion":"11.4.2","description":"A coding agent CLI powered by Claude","directories":{},"_nodeVersion":"22.12.0","_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/pcode_1.0.2_1764943466867_0.9123116912822054","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@aadithya2112/pcode","version":"1.0.3","keywords":["cli","ai","coding-agent","claude","automation"],"author":{"name":"aadithya2112"},"license":"MIT","_id":"@aadithya2112/pcode@1.0.3","maintainers":[{"name":"aadithya2112","email":"aadithyacps@gmail.com"}],"homepage":"https://github.com/aadithya2112/coding-agent-cli#readme","bugs":{"url":"https://github.com/aadithya2112/coding-agent-cli/issues"},"bin":{"pcode":"src/cli.ts"},"dist":{"shasum":"90d7e3978f5ffd48c854e45c97436cdb0d2c6c1e","tarball":"https://registry.npmjs.org/@aadithya2112/pcode/-/pcode-1.0.3.tgz","fileCount":12,"integrity":"sha512-rCchk/mxikO7QICI0aQxhuR9i4c7R6UbAZZDMFGfI/eJdm/Y82b6ifEaId2HZdkd7gV0zXITeMN0p8d7hoXJAw==","signatures":[{"sig":"MEUCICnnbB5i6DkbaLI2BcKMTa6rXaIvH/r52XRbjTWsAcZ2AiEA+5kAHfG3b2vQ5Evb8u6b5GeWiuJ4DvEdWNUiW5sp6F0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":46343},"type":"module","module":"index.ts","engines":{"bun":">=1.0.0"},"scripts":{"cli":"bun run src/cli.ts","dev":"bun run src/cli.ts --interactive","scenario":"bun run scripts/scenario.ts"},"_npmUser":{"name":"aadithya2112","email":"aadithyacps@gmail.com"},"repository":{"url":"git+https://github.com/aadithya2112/coding-agent-cli.git","type":"git"},"_npmVersion":"11.4.2","description":"A coding agent CLI powered by Claude","directories":{},"_nodeVersion":"22.12.0","_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/pcode_1.0.3_1764943498354_0.2919622279870042","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"@aadithya2112/pcode","version":"1.0.4","keywords":["cli","ai","coding-agent","claude","automation"],"author":{"name":"aadithya2112"},"license":"MIT","_id":"@aadithya2112/pcode@1.0.4","maintainers":[{"name":"aadithya2112","email":"aadithyacps@gmail.com"}],"homepage":"https://github.com/aadithya2112/coding-agent-cli#readme","bugs":{"url":"https://github.com/aadithya2112/coding-agent-cli/issues"},"bin":{"pcode":"src/cli.ts"},"dist":{"shasum":"857803cf1a49442a5adf28c3cb94a9aafc1cc649","tarball":"https://registry.npmjs.org/@aadithya2112/pcode/-/pcode-1.0.4.tgz","fileCount":12,"integrity":"sha512-+3uvlViAlwadRk+D4XRto9AZoX+v9k7J3hIekzA0IIulbJI6hfwbUhGX7HO4MV9sE+0o70I/Jb8Pxq7jyOeS0A==","signatures":[{"sig":"MEUCIQDmYTosRwUKcgwQ7mRxpakkhoNPihCNYBsO2//uHs07sAIgXaBUffLblPg5/ZQkGqHWxAURxj4oqoEoKZQvScQizPo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":46346},"type":"module","module":"index.ts","engines":{"bun":">=1.0.0"},"scripts":{"cli":"bun run src/cli.ts","dev":"bun run src/cli.ts --interactive","scenario":"bun run scripts/scenario.ts"},"_npmUser":{"name":"aadithya2112","email":"aadithyacps@gmail.com"},"repository":{"url":"git+https://github.com/aadithya2112/coding-agent-cli.git","type":"git"},"_npmVersion":"11.4.2","description":"A coding agent CLI powered by Claude","directories":{},"_nodeVersion":"22.12.0","_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/pcode_1.0.4_1764943750760_0.7006659624633296","host":"s3://npm-registry-packages-npm-production"}},"1.0.5":{"name":"@aadithya2112/pcode","version":"1.0.5","description":"A coding agent CLI powered by Claude","module":"index.ts","type":"module","bin":{"pcode":"src/cli.ts"},"scripts":{"cli":"bun run src/cli.ts","scenario":"bun run scripts/scenario.ts","dev":"bun run src/cli.ts --interactive"},"keywords":["cli","ai","coding-agent","claude","automation"],"author":{"name":"aadithya2112"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/aadithya2112/coding-agent-cli.git"},"engines":{"bun":">=1.0.0"},"devDependencies":{"@types/bun":"latest"},"peerDependencies":{"typescript":"^5"},"_id":"@aadithya2112/pcode@1.0.5","bugs":{"url":"https://github.com/aadithya2112/coding-agent-cli/issues"},"homepage":"https://github.com/aadithya2112/coding-agent-cli#readme","_nodeVersion":"22.12.0","_npmVersion":"11.4.2","dist":{"integrity":"sha512-3/uha5KrA1mc8FImD/uGW36yxB7vds281EYcJgG+OIg+8PmHlCcq3xmr3FDmKx4APe/x+FXZPu0jmtWrAuxY0g==","shasum":"d8a0e07c2755d34d4f813c4b01a8886c8f38d6a3","tarball":"https://registry.npmjs.org/@aadithya2112/pcode/-/pcode-1.0.5.tgz","fileCount":12,"unpackedSize":46353,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC50BoPMCLfGl1VCgv+gn+cFiAz1RF6aO832Zsc0H5WhAIhAI5qPFwsKyLmxfSJM7XAwbCThsarq406zvXBs9TpYR+8"}]},"_npmUser":{"name":"aadithya2112","email":"aadithyacps@gmail.com"},"directories":{},"maintainers":[{"name":"aadithya2112","email":"aadithyacps@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pcode_1.0.5_1764943838647_0.18198566106255076"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-05T13:45:40.835Z","modified":"2025-12-05T14:10:39.020Z","1.0.0":"2025-12-05T13:45:41.061Z","1.0.1":"2025-12-05T13:50:25.122Z","1.0.2":"2025-12-05T14:04:26.998Z","1.0.3":"2025-12-05T14:04:58.502Z","1.0.4":"2025-12-05T14:09:10.895Z","1.0.5":"2025-12-05T14:10:38.818Z"},"bugs":{"url":"https://github.com/aadithya2112/coding-agent-cli/issues"},"author":{"name":"aadithya2112"},"license":"MIT","homepage":"https://github.com/aadithya2112/coding-agent-cli#readme","keywords":["cli","ai","coding-agent","claude","automation"],"repository":{"type":"git","url":"git+https://github.com/aadithya2112/coding-agent-cli.git"},"description":"A coding agent CLI powered by Claude","maintainers":[{"name":"aadithya2112","email":"aadithyacps@gmail.com"}],"readme":"# Coding Agent CLI\n\nA lightweight coding agent prototype built with Bun that uses an orchestrator pattern to expose tools to an LLM (OpenRouter). The agent can read, write, search, and execute code while being guided by an AI model to accomplish tasks.\n\n## Features\n\n- **12 Built-in Tools**: Create, read, edit, delete files; list directories; search; run commands; git operations; environment variables\n- **LLM Integration**: Uses OpenRouter API (supports free models like Mistral 7B)\n- **Safety Constraints**: Path validation, command whitelisting, file size limits, timeouts\n- **Interactive & Single-task Modes**: REPL for continuous interaction or one-off task execution\n- **TypeScript**: Fully typed for better development experience\n\n## Prerequisites\n\n- [Bun](https://bun.sh) (v1.0+)\n- [OpenRouter API Key](https://openrouter.ai) (free tier available)\n\n## Installation\n\n### Install from npm\n\n```bash\nnpm install -g @aadithya2112/pcode\n```\n\nAfter installation, the `pcode` command will be available globally.\n\n### Set up your API key\n\nGet your free API key from [OpenRouter](https://openrouter.ai/keys).\n\n**Option 1: Global config (recommended)**\n\n```bash\nmkdir -p ~/.config/pcode\necho '{\"OPENROUTER_API_KEY\":\"your-api-key-here\"}' > ~/.config/pcode/config.json\n```\n\n**Option 2: Environment variable**\n\n```bash\nexport OPENROUTER_API_KEY=your-api-key-here\n```\n\nAdd to your `~/.zshrc` or `~/.bashrc` to make it permanent.\n\n**Option 3: Local .env file**\n\n```bash\necho \"OPENROUTER_API_KEY=your-api-key-here\" > .env\n```\n\n### Development Setup\n\n1. Clone this repository\n2. Install dependencies: `bun install`\n3. Copy `.env.example` to `.env` and add your OpenRouter API key\n\n## Usage\n\n### Single Task Execution\n\n```bash\npcode \"Create a TypeScript file that exports sayHello function\"\n```\n\nAfter completing the task, the agent will ask: \"Anything else you'd like me to do?\"\n\n- Type another task to continue working\n- Type \"exit\" or \"no\" to quit\n\n### Interactive Mode\n\n```bash\npcode --interactive\n```\n\nThen type your tasks:\n\n```\n> Create a file src/hello.ts\n> Read the file and show me\n> exit\n```\n\n### Project-Specific Tasks\n\n```bash\npcode -p /path/to/project \"Build the TypeScript project\"\n```\n\n### Run Example Scenario\n\n```bash\nbun run scripts/scenario.ts\n```\n\n## How It Works\n\n1. **User Input** → User provides a task description\n2. **LLM Processing** → Sends task + available tools to LLM via OpenRouter\n3. **Tool Calling** → LLM decides which tools to use and with what arguments\n4. **Tool Execution** → Agent executes the tools safely and validates results\n5. **Feedback Loop** → Results sent back to LLM for next iteration\n6. **Repeat** → Until LLM finishes or max iterations reached\n\n## Available Tools\n\n- `createFile` - Create a new file with content\n- `readFile` - Read file contents (with optional line ranges)\n- `editFile` - Replace text in a file\n- `deleteFile` - Delete a file\n- `listDirectory` - List files in a directory\n- `searchInFiles` - Search for patterns in files\n- `runCommand` - Execute shell commands (whitelisted)\n- `getFileInfo` - Get file metadata\n- `appendToFile` - Append content to end of file\n- `gitStatus` - Get git status\n- `getDiff` - Get git diff\n- `getEnvVar` - Read environment variables\n\n## Configuration\n\nEnvironment variables in `.env`:\n\n- `OPENROUTER_API_KEY` (required) - Your OpenRouter API key\n- `LLM_MODEL` (optional) - Model to use (default: `mistralai/mistral-7b-instruct:free`)\n\n### Free Models on OpenRouter\n\n- `mistralai/mistral-7b-instruct:free` (recommended)\n- `meta-llama/llama-2-7b-chat:free`\n- `openrouter/auto`\n\n## Safety Features\n\n- **Path Validation**: Only allows operations within project root or /tmp\n- **Command Whitelisting**: Only safe commands like `npm`, `git`, `node`, `bun`\n- **Blocked Commands**: `rm`, `sudo`, `chmod`, `reboot`, etc.\n- **File Size Limits**: 10MB max read, 100MB max write\n- **Timeouts**: 30s default command timeout\n\n## Example Tasks\n\n```bash\n# Create a TypeScript project structure\nbun run src/cli.ts \"Create a TypeScript project with src/, dist/, and package.json\"\n\n# Add documentation\nbun run src/cli.ts \"Create a detailed README.md for my project\"\n\n# Search and modify\nbun run src/cli.ts \"Search for all TODOs in the codebase and show me what needs to be fixed\"\n\n# Build and test\nbun run src/cli.ts \"Build the project with npm and show me any errors\"\n```\n\n## Project Structure\n\n```\ncoding-agent-cli/\n├── .env                  # API keys (GITIGNORED)\n├── .env.example          # Template for .env\n├── README.md             # This file\n├── package.json\n├── tsconfig.json\n├── PLAN.md              # Detailed implementation plan\n├── src/\n│   ├── types.ts         # TypeScript interfaces\n│   ├── cli.ts           # Entry point\n│   ├── orchestrator.ts  # Main orchestration loop\n│   ├── tools/\n│   │   ├── registry.ts  # Tool definitions & schemas\n│   │   └── executor.ts  # Tool implementations\n│   └── llm/\n│       └── client.ts    # OpenRouter LLM client\n├── scripts/\n│   └── scenario.ts      # Example scenario\n└── tests/\n    └── (future tests)\n```\n\n## Architecture\n\n### Core Components\n\n1. **Types** - TypeScript interfaces for tools, LLM, execution context\n2. **Tool Registry** - JSON schemas for all 12 tools (for LLM consumption)\n3. **Tool Executor** - Implements each tool with safety constraints\n4. **LLM Client** - OpenRouter integration with tool calling\n5. **Orchestrator** - Main loop: LLM → tools → results → repeat\n6. **CLI** - Command-line interface with REPL support\n\n### Data Flow\n\n```\nUser Task\n    ↓\nCLI (parse args, load env)\n    ↓\nOrchestrator (initialize)\n    ↓\nLLM Client (send to OpenRouter with tools)\n    ↓\nLLM Response (with tool_calls)\n    ↓\nTool Executor (validate + execute)\n    ↓\nTool Results\n    ↓\nLLM Client (send back for next iteration)\n    ↓\nRepeat until done\n    ↓\nFinal Response → User\n```\n\n## Development\n\n### Scripts\n\n```bash\n# Run CLI with task\nbun run src/cli.ts \"Your task here\"\n\n# Interactive mode\nbun run src/cli.ts --interactive\n\n# Run scenario example\nbun run scripts/scenario.ts\n\n# Type checking (built into bun)\nbun check\n```\n\n### Adding New Tools\n\n1. Define in `src/types.ts` (TOOL_NAMES enum)\n2. Add schema to `src/tools/registry.ts`\n3. Implement in `src/tools/executor.ts`\n4. Add to allowed commands if needed\n\n## Limitations & Future Work\n\n### Current Limitations\n\n- Single-threaded execution (no parallel tool calls yet)\n- In-memory conversation history only\n- No RAG for large codebases\n- Basic error messages\n- No input confirmation for destructive operations\n\n### Future Enhancements\n\n- Persistent conversation history (SQLite)\n- RAG for codebase context\n- Multi-tool parallelization\n- Streaming LLM responses\n- Better prompt engineering\n- Support for multiple LLM providers\n- Tool result caching\n\n## Troubleshooting\n\n### \"OPENROUTER_API_KEY not set\"\n\nMake sure you've created a `.env` file with your API key:\n\n```bash\ncp .env.example .env\n# Edit .env and add your key\n```\n\n### \"Command not allowed\"\n\nThe command you tried to run is blocked for safety. Check `src/types.ts` for allowed commands.\n\n### \"Path outside allowed directories\"\n\nFile operations are restricted to:\n\n- Your project root\n- /tmp directory\n\n### \"LLM API error\"\n\nCheck:\n\n1. Your API key is valid\n2. You have free credits on OpenRouter\n3. Your internet connection is working\n\n## License\n\nMIT\n\n## Resources\n\n- [OpenRouter](https://openrouter.ai) - LLM provider\n- [Bun](https://bun.sh) - Runtime\n- [OpenAI API Docs](https://platform.openai.com/docs/api-reference/chat/create) - Tool calling spec\n","readmeFilename":"README.md"}