@gaberrb/polypus 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +235 -0
- package/dist/index.js +2786 -0
- package/dist/index.js.map +1 -0
- package/package.json +62 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Gabriel Rios
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
# Polypus 🐙
|
|
2
|
+
|
|
3
|
+
An agentic coding harness that makes **any** AI API generate and apply code —
|
|
4
|
+
even models **without** native tool-calling. Bring your own keys: OpenRouter,
|
|
5
|
+
Ollama, Anthropic, or any OpenAI-compatible endpoint. Run one agent, or split a
|
|
6
|
+
task across **several agents working in parallel** in isolated git worktrees.
|
|
7
|
+
|
|
8
|
+
- 🔌 **Any provider.** OpenRouter and Ollama out of the box (both OpenAI-compatible), plus a generic endpoint and native Anthropic.
|
|
9
|
+
- 🧩 **Tool-calling for everyone.** Models with function-calling use it natively; models without it get an XML tool protocol injected into the prompt and parsed back — so base/local models can code too.
|
|
10
|
+
- 🔐 **Permission modes.** `plan` (read-only), `review` (confirm each action), `bypass` (auto-approve), with a path allow-list.
|
|
11
|
+
- 🐝 **Parallel swarm.** A lead agent decomposes a task into subtasks; workers run concurrently in git worktrees and merge at the end.
|
|
12
|
+
- 🪄 **Setup wizard.** Interactive onboarding for keys, models, and permissions.
|
|
13
|
+
- 🌎 **Bilingual UI.** Portuguese (pt-BR, default) and English.
|
|
14
|
+
- 🕵️ **No telemetry.** Nothing leaves your machine except calls to the providers you configure.
|
|
15
|
+
|
|
16
|
+
> Status: early MVP. Expect rough edges.
|
|
17
|
+
|
|
18
|
+
## Install
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
git clone <this-repo> polypus && cd polypus
|
|
22
|
+
npm install
|
|
23
|
+
npm run build
|
|
24
|
+
npm link # optional: makes `polypus` available globally
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Requires Node.js 20+.
|
|
28
|
+
|
|
29
|
+
## Quickstart
|
|
30
|
+
|
|
31
|
+
### Option A — guided
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
polypus setup
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
The wizard walks you through adding one or more agents, choosing how API keys are
|
|
38
|
+
stored (env var recommended), and setting the default permission mode.
|
|
39
|
+
|
|
40
|
+
### Option B — manual
|
|
41
|
+
|
|
42
|
+
**OpenRouter** (hosted):
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
export OPENROUTER_API_KEY=sk-or-...
|
|
46
|
+
polypus add-agent or \
|
|
47
|
+
--provider openrouter \
|
|
48
|
+
--model "anthropic/claude-3.5-sonnet" \
|
|
49
|
+
--api-key '${OPENROUTER_API_KEY}'
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
**Ollama** (local, no key, emulated tools by default):
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
# ollama serve && ollama pull llama3.1
|
|
56
|
+
polypus add-agent local --provider ollama --model llama3.1
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Then run a task in the current directory:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
polypus run "create a Fastify server in src/server.ts with a /health route"
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Or just launch the interactive experience (banner + REPL):
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
polypus # bare command → interactive; first run opens the setup wizard
|
|
69
|
+
polypus run # same interactive session
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
> When you pick **Ollama** in the wizard, Polypus detects your running instance
|
|
73
|
+
> and lists the models you already have installed — no need to remember exact
|
|
74
|
+
> tags like `llama3.1:8b`. For **OpenRouter**, it pulls the live catalog so you
|
|
75
|
+
> can filter by price, context and tool support and pick a model from a list.
|
|
76
|
+
|
|
77
|
+
## Discovering models
|
|
78
|
+
|
|
79
|
+
Browse the OpenRouter catalog from the terminal — price (USD per 1M tokens, in/out),
|
|
80
|
+
context window, and whether the model supports native tool-calling:
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
polypus models --tools --max-price 1 --sort price # cheap models that support tools
|
|
84
|
+
polypus models --search claude --sort price-desc # all Claude models, priciest first
|
|
85
|
+
polypus models --free # free models only
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
The setup wizard uses the same data: choosing OpenRouter opens an interactive
|
|
89
|
+
browser with search, filters (tools-only, free-only) and sorting, then a picker
|
|
90
|
+
showing each model's price, tool badge and context.
|
|
91
|
+
|
|
92
|
+
## Commands
|
|
93
|
+
|
|
94
|
+
| Command | Description |
|
|
95
|
+
| --- | --- |
|
|
96
|
+
| `polypus setup` | Interactive wizard (agents, keys, permissions). |
|
|
97
|
+
| `polypus add-agent <name> --provider <p> --model <m> [--api-key ...] [--base-url ...] [--tool-mode auto\|native\|emulated] [--set-default]` | Register an agent. |
|
|
98
|
+
| `polypus remove-agent <name>` | Remove an agent. |
|
|
99
|
+
| `polypus list-agents` | List configured agents. |
|
|
100
|
+
| `polypus run [task] [--agent <name>] [--mode plan\|review\|bypass] [--max-steps <n>]` | Run a task, or open a REPL if no task is given. |
|
|
101
|
+
| `polypus swarm <task> [--agents a,b] [--max-subtasks <n>]` | Split a task across agents in parallel worktrees. |
|
|
102
|
+
| `polypus models [--search x] [--tools] [--free] [--max-price <usd>] [--sort price\|price-desc\|context\|name] [--limit <n>]` | Browse the OpenRouter catalog (price, context, tool support). |
|
|
103
|
+
|
|
104
|
+
### Interactive slash commands (in `polypus run`)
|
|
105
|
+
|
|
106
|
+
```
|
|
107
|
+
/agents list configured agents
|
|
108
|
+
/agent <name> switch the active agent
|
|
109
|
+
/add add a new agent (wizard)
|
|
110
|
+
/remove <name> remove an agent
|
|
111
|
+
/plan read-only mode
|
|
112
|
+
/review confirm each write / command
|
|
113
|
+
/bypass auto-approve
|
|
114
|
+
/allow <glob> add a path to the allow-list
|
|
115
|
+
/reset clear the conversation
|
|
116
|
+
/help list commands
|
|
117
|
+
/exit quit
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
## How non-tool models "code"
|
|
121
|
+
|
|
122
|
+
Models with native function-calling (most hosted models) use it directly. For
|
|
123
|
+
models **without** it, Polypus injects a strict XML protocol into the system
|
|
124
|
+
prompt and parses the model's text output:
|
|
125
|
+
|
|
126
|
+
```xml
|
|
127
|
+
<polypus:tool name="write_file">
|
|
128
|
+
<arg name="path">src/index.ts</arg>
|
|
129
|
+
<arg name="content">console.log("hello");</arg>
|
|
130
|
+
</polypus:tool>
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
The parser tolerates angle brackets inside code. When the model stalls or claims
|
|
134
|
+
it "can't create files", Polypus re-sends a reinforcement message ("yes, you ARE
|
|
135
|
+
allowed to act now") up to a few times before giving up. When the work is done,
|
|
136
|
+
the model calls the `finish` tool.
|
|
137
|
+
|
|
138
|
+
Set the path per agent with `--tool-mode`: `auto` (native for hosted, emulated
|
|
139
|
+
for Ollama), `native`, or `emulated`.
|
|
140
|
+
|
|
141
|
+
## Language / Idioma
|
|
142
|
+
|
|
143
|
+
The interface is bilingual: **pt-BR (default)** and **en**. Resolution order:
|
|
144
|
+
`--lang` flag → `POLYPUS_LANG` env → `locale` in the config → pt-BR.
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
polypus --lang en run "create a CLI entrypoint"
|
|
148
|
+
POLYPUS_LANG=en polypus list-agents
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
The setup wizard asks for the language first and saves it to the config. The
|
|
152
|
+
agent is also instructed to talk back to you in the configured language.
|
|
153
|
+
|
|
154
|
+
## Permissions
|
|
155
|
+
|
|
156
|
+
| Mode | File writes | Commands |
|
|
157
|
+
| --- | --- | --- |
|
|
158
|
+
| `plan` | blocked | blocked |
|
|
159
|
+
| `review` | confirm each | confirm (unless pre-approved) |
|
|
160
|
+
| `bypass` | auto | auto |
|
|
161
|
+
|
|
162
|
+
All file access is restricted to the workspace and the configured **allow-list**
|
|
163
|
+
globs; the **deny-list** (e.g. `.git/**`, `**/.env`) always wins.
|
|
164
|
+
|
|
165
|
+
## Swarm (parallel agents)
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
polypus swarm "add a REST API and a matching test suite"
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
The lead agent splits the task into subtasks, each worker runs in its own git
|
|
172
|
+
worktree (in `bypass` mode, since the worktree is throwaway), and the branches
|
|
173
|
+
are merged back sequentially. Conflicting branches are kept for manual
|
|
174
|
+
inspection rather than force-merged.
|
|
175
|
+
|
|
176
|
+
## Configuration
|
|
177
|
+
|
|
178
|
+
Stored at `~/.polypus/config.json` (override the directory with `POLYPUS_HOME`).
|
|
179
|
+
API keys may be inline or, preferably, an env reference.
|
|
180
|
+
|
|
181
|
+
Polypus also loads a `.env` file from `~/.polypus/.env` (and the current
|
|
182
|
+
directory) at startup, so you can keep secrets there without relying on the OS
|
|
183
|
+
to propagate environment variables to your shell:
|
|
184
|
+
|
|
185
|
+
```dotenv
|
|
186
|
+
# ~/.polypus/.env
|
|
187
|
+
OPENROUTER_API_KEY=sk-or-...
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Real environment variables always win over `.env` values. Example config:
|
|
191
|
+
|
|
192
|
+
```json
|
|
193
|
+
{
|
|
194
|
+
"version": 1,
|
|
195
|
+
"locale": "pt-BR",
|
|
196
|
+
"defaultAgent": "or",
|
|
197
|
+
"agents": [
|
|
198
|
+
{
|
|
199
|
+
"name": "or",
|
|
200
|
+
"provider": "openrouter",
|
|
201
|
+
"baseUrl": "https://openrouter.ai/api/v1",
|
|
202
|
+
"model": "anthropic/claude-3.5-sonnet",
|
|
203
|
+
"apiKey": "${OPENROUTER_API_KEY}",
|
|
204
|
+
"toolMode": "auto"
|
|
205
|
+
}
|
|
206
|
+
],
|
|
207
|
+
"permissions": {
|
|
208
|
+
"mode": "review",
|
|
209
|
+
"allow": ["**/*"],
|
|
210
|
+
"deny": [".git/**", ".polypus/**", "**/.env"],
|
|
211
|
+
"allowedCommands": []
|
|
212
|
+
}
|
|
213
|
+
}
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
## Development
|
|
217
|
+
|
|
218
|
+
```bash
|
|
219
|
+
npm run dev # build in watch mode
|
|
220
|
+
npm run typecheck
|
|
221
|
+
npm test # vitest
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
## Author
|
|
225
|
+
|
|
226
|
+
**Gabriel Rios**
|
|
227
|
+
|
|
228
|
+
[](https://github.com/GaberRB)
|
|
229
|
+
[](https://www.linkedin.com/in/gabriel-riosb/)
|
|
230
|
+
|
|
231
|
+
Contributions, issues and feedback are welcome — open an issue or a PR.
|
|
232
|
+
|
|
233
|
+
## License
|
|
234
|
+
|
|
235
|
+
[MIT](LICENSE) © Gabriel Rios
|