{"id":24600920,"url":"https://github.com/polka-codes/polka-codes","last_synced_at":"2026-04-07T05:03:57.049Z","repository":{"id":272852280,"uuid":"913664762","full_name":"polka-codes/polka-codes","owner":"polka-codes","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-30T22:40:57.000Z","size":3464,"stargazers_count":16,"open_issues_count":15,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-03-31T00:31:20.261Z","etag":null,"topics":["ai","bun","coding-assistant","typescript"],"latest_commit_sha":null,"homepage":"https://polka.codes","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/polka-codes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-01-08T05:53:41.000Z","updated_at":"2026-03-30T22:41:01.000Z","dependencies_parsed_at":"2025-04-10T04:24:26.581Z","dependency_job_id":"c79d2e20-37d1-4450-a3c2-3bf455df41cf","html_url":"https://github.com/polka-codes/polka-codes","commit_stats":null,"previous_names":["polka-codes/polka-codes"],"tags_count":184,"template":false,"template_full_name":null,"purl":"pkg:github/polka-codes/polka-codes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polka-codes%2Fpolka-codes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polka-codes%2Fpolka-codes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polka-codes%2Fpolka-codes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polka-codes%2Fpolka-codes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/polka-codes","download_url":"https://codeload.github.com/polka-codes/polka-codes/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polka-codes%2Fpolka-codes/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31316093,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","bun","coding-assistant","typescript"],"created_at":"2025-01-24T14:19:23.962Z","updated_at":"2026-04-02T21:00:01.465Z","avatar_url":"https://github.com/polka-codes.png","language":"TypeScript","funding_links":[],"categories":["Frameworks \u0026 Libraries"],"sub_categories":["Copilot Extensions \u0026 Alternatives"],"readme":"# Polka Codes - AI-Powered Coding Assistant\n\n[![CI](https://github.com/polka-codes/polka-codes/actions/workflows/ci.yml/badge.svg)](https://github.com/polka-codes/polka-codes/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/@polka-codes/cli.svg)](https://www.npmjs.com/package/@polka-codes/cli)\n[![npm downloads](https://img.shields.io/npm/dm/@polka-codes/cli.svg)](https://www.npmjs.com/package/@polka-codes/cli)\n[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL%203.0-blue.svg)](LICENSE)\n[![Bun Version](https://img.shields.io/badge/Bun-v1.0.0+-brightgreen)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)](https://www.typescriptlang.org)\n\n\u003e **Note**\n\u003e This project is under active development. APIs and features may evolve, but we strive to maintain backward compatibility when possible.\n\nPolka Codes is a powerful TypeScript-based AI coding assistant framework that helps developers with task planning, code generation, and more. It uses natural language interactions, a multi-agent system, a command-line interface, and seamless GitHub integration to streamline your development workflow.\n\n## ✨ Features\n\n- 📝 **Task Planning**: Create detailed implementation plans for your tasks using the `plan` command\n- 💻 **Code Generation**: Implement features from a plan or a simple description with the `code` command\n- 🐛 **Automated Debugging**: Automatically fix failing tests or commands with the `fix` command\n- 🔍 **Code Review**: Get AI-powered feedback on your pull requests and local changes with automatic fix application\n- 🤖 **AI-Assisted Git Workflow**: Generate commit messages and create pull requests with the `commit` and `pr` commands\n- 💾 **Checkpoint \u0026 Resume**: Save and restore work state with the `checkpoints` and `continue` commands\n- 🎯 **Custom Scripts**: Define and execute custom TypeScript scripts and shell commands with the `run` and `init` commands\n- 🤝 **Multi-Agent System**: Specialized AI agents (Architect, Coder, etc.) collaborate on complex tasks\n- 🔧 **Simple Setup**: Quickly initialize your project configuration with `init`\n- 🔄 **GitHub Integration**: GitHub Actions integration for PR/issue mentions\n- 📦 **Extensible Architecture**: Modular design for adding AI providers, tools, and agents\n- ⚡ **Type Safety**: Fully typed with TypeScript for better DX\n- 🧪 **Thoroughly Tested**: 800+ tests using `bun:test` with snapshot testing\n- 🤖 **Multiple AI Providers**: Anthropic Claude, Google Vertex, DeepSeek, OpenAI, OpenRouter, Ollama\n- 🔌 **MCP Support**: Consume tools from external MCP servers and expose workflows via MCP server\n- 🚀 **Auto-Fix**: Automatically detect and fix lint/type errors after code changes\n\n## Quick Start\n\n### Installation\n\n```bash\n# Install globally using npm\nnpm install -g @polka-codes/cli\n\n# Or run directly using npx\nnpx @polka-codes/cli \"your task description\"\n```\n\n### Example Workflow\n\nHere's an example of a typical development workflow using Polka Codes:\n\n```bash\n# 1. Create a detailed implementation plan for a task\npolka plan --plan-file auth.plan.md \"Implement JWT-based auth\"\n\n# 2. Implement the feature based on the plan\npolka code --file auth.plan.md\n\n# 3. Fix any issues that arise (e.g., failing tests)\npolka fix \"bun test\"\n\n# 4. Commit your changes with an AI-generated message\npolka commit -a\n\n# 5. Create a pull request\npolka pr\n```\n\n## Code Review\n\nThe `review` command provides AI-powered code reviews for your projects. It can be used to review GitHub pull requests or local changes. The command can also attempt to automatically fix the issues it finds. Use the `--loop` option to have it re-review its own changes until the review is clean or the loop limit is reached.\n\n### Reviewing Pull Requests\n\nTo review a pull request, use the `--pr` option with the pull request number. This feature requires the [GitHub CLI](https://cli.github.com/) (`gh`) to be installed and authenticated.\n\n```bash\n# Review a pull request by number\npolka review --pr 123\n\n# Review and automatically apply feedback in a loop (up to 3 times)\npolka review --pr 123 --loop 3\n```\n\n### Reviewing Local Changes\n\nTo review local changes, run the `review` command without any arguments. It will automatically detect changes in the following order:\n1. Staged changes (`git diff --staged`)\n2. Unstaged changes (`git diff`)\n\nIf no local changes are found, it will fall back to reviewing the diff between the current branch and the repository's default branch (e.g., `main` or `master`). This also requires `gh`.\n\n```bash\n# Review staged or unstaged changes\npolka review\n\n# Review and apply feedback\npolka review --yes\n```\n\n### JSON Output\n\nFor programmatic use, you can get the review in JSON format by adding the `--json` flag.\n\n```bash\npolka review --json\n```\n\nFor more information, see the [CLI README](packages/cli/README.md).\n\n## Custom Scripts\n\nPolka Codes supports defining and executing custom automation scripts in your `.polkacodes.yml` configuration file. This allows you to create reusable TypeScript scripts and shell commands for common development tasks.\n\n### Script Types\n\nYou can define four types of scripts:\n\n1. **Simple Shell Command**: A quick one-liner\n2. **Command with Description**: A shell command with metadata\n3. **TypeScript Script**: An in-process TypeScript file with full access to Polka Codes APIs\n4. **Workflow Script**: A reference to a workflow YAML file\n\n### Configuration\n\nAdd scripts to your `.polkacodes.yml`:\n\n```yaml\nscripts:\n  # Simple shell command\n  test: bun test\n\n  # Command with description\n  lint:\n    command: bun run lint\n    description: Run linter\n\n  # TypeScript script\n  deploy:\n    script: .polka-scripts/deploy.ts\n    description: Deploy to production\n    timeout: 300000  # 5 minutes\n    permissions:\n      fs: write\n      network: true\n```\n\n### Running Scripts\n\n```bash\n# List all available scripts\npolka run --list\n\n# Run a specific script\npolka run deploy\n\n# Run with arguments\npolka run deploy -- --production --force\n\n# Quick execution - runs script directly\npolka test  # Runs the 'test' script\n```\n\n### Creating TypeScript Scripts\n\nGenerate a new script template:\n\n```bash\npolka init script my-script\n```\n\nThis creates `.polka-scripts/my-script.ts` with a template:\n\n```typescript\nimport { code, commit } from '@polka-codes/cli'\n\nexport async function main(args: string[]) {\n  console.log('Running script: my-script')\n  console.log('Arguments:', args)\n\n  // Your automation here\n  // await code({ task: 'Add feature', interactive: false })\n  // await commit({ all: true, context: 'Feature complete' })\n\n  console.log('Script completed successfully')\n}\n\nif (import.meta.main) {\n  main(process.argv.slice(2))\n}\n```\n\n### Script Permissions\n\nTypeScript scripts support declaring permissions (currently advisory for future sandboxing):\n\n```yaml\nscripts:\n  risky-script:\n    script: .polka-scripts/risky.ts\n    permissions:\n      fs: write        # read, write, or none\n      network: true     # true or false\n      subprocess: true  # true or false\n    timeout: 60000      # Execution timeout in milliseconds\n    memory: 512         # Memory limit in MB (64-8192)\n```\n\n**Important**: TypeScript scripts currently run in-process with full permissions. Permission declarations are advisory only for future sandboxing implementation.\n\n### Built-in Commands\n\nThe following command names are reserved and cannot be used for custom scripts:\n- `code`, `commit`, `pr`, `review`, `fix`, `plan`, `workflow`, `run`, `init`, `meta`\n\n## Checkpoint \u0026 Resume\n\nPolka Codes automatically creates checkpoints during agent runs, allowing you to save your work state and resume later.\n\n### Listing Checkpoints\n\nView all available checkpoints:\n\n```bash\npolka checkpoints\n```\n\nOutput example:\n```\nFound 2 checkpoint(s):\n\n1. feature-complete - Jan 4, 2025, 3:00:00 PM (5m ago)\n   Completed: 10 task(s)\n\n2. initial-state - Jan 4, 2025, 2:00:00 PM (1h 5m ago)\n   Queue: 15 task(s)\n   Next: Implement user authentication\n\nResume with:\n  bun polka continue feature-complete\n```\n\nFor more details:\n\n```bash\npolka checkpoints --verbose\n```\n\n### Resuming from Checkpoints\n\nResume from the most recent checkpoint:\n\n```bash\npolka continue\n```\n\nResume from a specific checkpoint:\n\n```bash\npolka continue feature-complete\n```\n\nThe continue command will show you:\n- What tasks were completed\n- What tasks failed\n- What tasks are pending\n- Instructions to manually restore and continue\n\n**Note**: Full automatic resume is planned for a future release. Currently, the command provides clear instructions for manual restoration.\n\n### Working Directory\n\nCheckpoints are stored in your project's `.polka/agent-state/checkpoints/` directory. Each checkpoint contains:\n- Session ID and timestamp\n- Task queue status\n- Completed and failed tasks\n- Execution history\n- Metrics and performance data\n\n## MCP Integration\n\nPolka Codes supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for both consuming external tools and exposing your own workflows as MCP tools.\n\n### Consuming MCP Tools\n\nYou can configure external MCP servers in your `.polkacodes.yml` to make their tools available to AI agents:\n\n```yaml\nmcpServers:\n  filesystem:\n    command: npx\n    args: [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/allowed/path\"]\n    tools:\n      read_file: true\n      write_file: true\n    # Optionally configure specific AI provider for tools\n    # provider: anthropic\n    # model: claude-3-5-sonnet-20241022\n\n  database:\n    command: /path/to/custom-server\n    env:\n      DATABASE_URL: \"postgresql://...\"\n```\n\nWhen MCP servers are configured, their tools are automatically exposed to AI agents in the `code`, `fix`, `plan`, and `task` workflows. Tools are named with the pattern `{serverName}/{toolName}` (e.g., `filesystem/read_file`).\n\n### Exposing Workflows via MCP Server\n\nPolka Codes can run as an MCP server, exposing your high-level workflows to Claude Code.\n\nStart the MCP server:\n\n```bash\npolka mcp-server\n```\n\nThe server exposes these workflow tools:\n- `code`: Execute coding tasks\n- `review`: Review code changes\n- `plan`: Create implementation plans\n- `fix`: Fix failing tests or commands\n- `commit`: Generate commit messages\n\n**Configuration with Claude Code:**\n\nAdd the MCP server to your Claude Code configuration:\n\n```bash\nclaude mcp add polka polka mcp-server\n```\n\nOr manually edit `~/.claude/config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"polka\": {\n      \"command\": \"polka\",\n      \"args\": [\"mcp-server\"]\n    }\n  }\n}\n```\n\nFor detailed MCP usage instructions and configuration options, see [MCP_GUIDE.md](MCP_GUIDE.md).\n\n## Project Structure\n\nThe project is organized as a monorepo with the following packages:\n\n| Package | Description |\n|---|---|\n| [`core`](/packages/core) | Core AI services, agent implementations, and tooling. |\n| [`cli`](/packages/cli) | Command-line interface for interacting with AI services. |\n| [`cli-shared`](/packages/cli-shared) | Shared utilities and types for CLI packages. |\n| [`github`](/packages/github) | GitHub integration, including the GitHub Action. |\n| [`runner`](/packages/runner) | Service for running agents and managing tasks. |\n\n## Getting Started\n\n### Prerequisites\n\n- [Bun](https://bun.sh/) (v1.0.0 or higher)\n- [ripgrep](https://github.com/BurntSushi/ripgrep#installation) (required for the file search tool)\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/polka-codes/polka-codes.git\ncd polka-codes\n\n# Install dependencies\nbun install\n```\n\n### Available Scripts\n\n- `bun build`: Build all packages.\n- `bun lint`: Check for linting and formatting errors.\n- `bun fix`: Automatically fix linting and formatting issues.\n- `bun check`: Run type checking and linting.\n- `bun typecheck`: Run type checking only.\n- `bun test`: Run tests across all packages.\n- `bun clean`: Remove build artifacts.\n- `bun cli`: Run the CLI in development mode.\n- `bun pr`: A shortcut for `bun cli pr`.\n- `bun commit`: A shortcut for `bun cli commit`.\n- `bun codegen`: Generate GraphQL types for the GitHub package.\n\n## Contributing\n\nIf you're contributing to this project, please refer to [AGENTS.md](AGENTS.md) for:\n- Comprehensive project architecture and workflow system documentation\n- Code conventions and development guidelines\n- Tool system patterns and multi-agent architecture\n- Important implementation notes\n\n## Configuration\n\nA [`.polkacodes.yml`](.polkacodes.yml) configuration file can be used to customize the behavior of polka-codes. An example configuration file is provided in the repository as [`example.polkacodes.yml`](example.polkacodes.yml).\n\nFor detailed configuration options, refer to the example file, which includes comprehensive comments for each setting.\n\n### Tool Format\n\nYou can specify the format for tool integration using the `toolFormat` option in your `.polkacodes.yml` file. This setting determines how the AI model interacts with the available tools.\n\n-   **`native`**: Uses the model's native tool-use capabilities via the Vercel AI SDK. More efficient and leads to better results, but not supported by all models. Check your model provider's documentation for compatibility.\n\n-   **`polka-codes`** (default): Uses a custom XML-based format for tool calls. Designed to be compatible with a wide range of models but may consume more tokens compared to the `native` format.\n\nYou can set the `toolFormat` globally or for specific agents or commands.\n\nExample:\n```yaml\n# .polkacodes.yml\ntoolFormat: \"native\"\n```\n\n## Environment Variables\n\nThe following environment variables can be used to configure Polka Codes. Note that command line options take precedence over environment variables, which in turn take precedence over the configuration file.\n\n| Variable | Description |\n|---|---|\n| `POLKA_API_PROVIDER` | Specify the default AI service provider. |\n| `POLKA_MODEL` | Specify the default AI model to use. |\n| `POLKA_API_KEY` | Default API key for the selected provider. |\n| `POLKA_BUDGET` | Set the budget limit for AI service usage (defaults to 1000). |\n| `ANTHROPIC_API_KEY` | API key for Anthropic Claude service. |\n| `OPENROUTER_API_KEY` | API key for OpenRouter service. |\n| `DEEPSEEK_API_KEY` | API key for DeepSeek service. |\n\n## License\n\nThis project is licensed under the [AGPL-3.0 License](LICENSE).\n\n## Credits\n\nThis project is heavily inspired by the [Cline](https://github.com/cline/cline) project.\n\n---\n*Generated by polka.codes*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolka-codes%2Fpolka-codes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolka-codes%2Fpolka-codes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolka-codes%2Fpolka-codes/lists"}