rigcode 0.1.0__tar.gz
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.
- rigcode-0.1.0/.gitignore +11 -0
- rigcode-0.1.0/CHANGELOG.md +12 -0
- rigcode-0.1.0/LICENSE +21 -0
- rigcode-0.1.0/PKG-INFO +203 -0
- rigcode-0.1.0/README.md +171 -0
- rigcode-0.1.0/pyproject.toml +61 -0
- rigcode-0.1.0/rigcode/__init__.py +4 -0
- rigcode-0.1.0/rigcode/__main__.py +4 -0
- rigcode-0.1.0/rigcode/agent/__init__.py +0 -0
- rigcode-0.1.0/rigcode/agent/loop.py +627 -0
- rigcode-0.1.0/rigcode/agent/mentions.py +70 -0
- rigcode-0.1.0/rigcode/agent/prompts.py +195 -0
- rigcode-0.1.0/rigcode/agent/runtime.py +535 -0
- rigcode-0.1.0/rigcode/agent/session.py +165 -0
- rigcode-0.1.0/rigcode/agent/state.py +161 -0
- rigcode-0.1.0/rigcode/cli.py +283 -0
- rigcode-0.1.0/rigcode/config.py +284 -0
- rigcode-0.1.0/rigcode/doctor.py +158 -0
- rigcode-0.1.0/rigcode/extensions.py +275 -0
- rigcode-0.1.0/rigcode/hooks.py +142 -0
- rigcode-0.1.0/rigcode/llm/__init__.py +0 -0
- rigcode-0.1.0/rigcode/llm/client.py +259 -0
- rigcode-0.1.0/rigcode/llm/probe.py +229 -0
- rigcode-0.1.0/rigcode/llm/stream.py +240 -0
- rigcode-0.1.0/rigcode/llm/textmode.py +161 -0
- rigcode-0.1.0/rigcode/llm/types.py +92 -0
- rigcode-0.1.0/rigcode/llm/wire.py +76 -0
- rigcode-0.1.0/rigcode/mcp.py +329 -0
- rigcode-0.1.0/rigcode/permissions.py +221 -0
- rigcode-0.1.0/rigcode/prompts/agents/coder.md +13 -0
- rigcode-0.1.0/rigcode/prompts/agents/debugger.md +14 -0
- rigcode-0.1.0/rigcode/prompts/agents/explore.md +22 -0
- rigcode-0.1.0/rigcode/prompts/agents/plan.md +21 -0
- rigcode-0.1.0/rigcode/prompts/agents/researcher.md +14 -0
- rigcode-0.1.0/rigcode/prompts/agents/reviewer.md +18 -0
- rigcode-0.1.0/rigcode/prompts/agents/verifier.md +15 -0
- rigcode-0.1.0/rigcode/prompts/commit.md +5 -0
- rigcode-0.1.0/rigcode/prompts/compact.md +24 -0
- rigcode-0.1.0/rigcode/prompts/init.md +10 -0
- rigcode-0.1.0/rigcode/prompts/system.md +27 -0
- rigcode-0.1.0/rigcode/tools/__init__.py +0 -0
- rigcode-0.1.0/rigcode/tools/base.py +245 -0
- rigcode-0.1.0/rigcode/tools/bashsafety.py +262 -0
- rigcode-0.1.0/rigcode/tools/editmatch.py +367 -0
- rigcode-0.1.0/rigcode/tools/files.py +534 -0
- rigcode-0.1.0/rigcode/tools/interact.py +69 -0
- rigcode-0.1.0/rigcode/tools/search.py +309 -0
- rigcode-0.1.0/rigcode/tools/shell.py +424 -0
- rigcode-0.1.0/rigcode/tools/skill.py +37 -0
- rigcode-0.1.0/rigcode/tools/task.py +54 -0
- rigcode-0.1.0/rigcode/tools/todo.py +62 -0
- rigcode-0.1.0/rigcode/tools/web.py +346 -0
- rigcode-0.1.0/rigcode/ui/__init__.py +0 -0
- rigcode-0.1.0/rigcode/ui/base.py +69 -0
- rigcode-0.1.0/rigcode/ui/commands.py +581 -0
- rigcode-0.1.0/rigcode/ui/plain.py +321 -0
- rigcode-0.1.0/rigcode/ui/render.py +207 -0
- rigcode-0.1.0/rigcode/ui/terminal.py +1154 -0
- rigcode-0.1.0/rigcode/utils/__init__.py +0 -0
- rigcode-0.1.0/rigcode/utils/files.py +176 -0
- rigcode-0.1.0/rigcode/utils/frontmatter.py +38 -0
- rigcode-0.1.0/rigcode/utils/globmatch.py +91 -0
- rigcode-0.1.0/rigcode/utils/jsonrepair.py +110 -0
- rigcode-0.1.0/rigcode/utils/paths.py +83 -0
- rigcode-0.1.0/rigcode/utils/text.py +105 -0
- rigcode-0.1.0/tests/conftest.py +37 -0
- rigcode-0.1.0/tests/helpers.py +61 -0
- rigcode-0.1.0/tests/mock_server.py +165 -0
- rigcode-0.1.0/tests/test_agent_e2e.py +391 -0
- rigcode-0.1.0/tests/test_bashsafety.py +68 -0
- rigcode-0.1.0/tests/test_cli.py +68 -0
- rigcode-0.1.0/tests/test_config_session_render.py +113 -0
- rigcode-0.1.0/tests/test_discover.py +43 -0
- rigcode-0.1.0/tests/test_editmatch.py +98 -0
- rigcode-0.1.0/tests/test_file_tools.py +128 -0
- rigcode-0.1.0/tests/test_llm_parsing.py +129 -0
- rigcode-0.1.0/tests/test_permissions.py +84 -0
- rigcode-0.1.0/tests/test_terminal_ui.py +141 -0
rigcode-0.1.0/.gitignore
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0 - 2026-11-19
|
|
4
|
+
|
|
5
|
+
First public release.
|
|
6
|
+
|
|
7
|
+
- Terminal coding agent for OpenAI-compatible servers: llama.cpp, Ollama, LM Studio, vLLM and SGLang.
|
|
8
|
+
- Finds a local server and its loaded model automatically when none is configured, and warns when Ollama's or LM Studio's context window is too small for an agent.
|
|
9
|
+
- Prompt-cache-aware design for slow hardware: fixed prompt prefix, append-only history, forked subagents, background warm-up.
|
|
10
|
+
- Tools: Read, Edit, MultiEdit, Write, Grep, Glob (files and directories), Bash with background shells, WebFetch, WebSearch, TodoWrite, Task, Skill, AskUser.
|
|
11
|
+
- Permission modes, allow/deny/ask rules, hooks, MCP servers, skills, custom agents and commands. Reads `AGENTS.md`, `CLAUDE.md` and `.claude/` setups.
|
|
12
|
+
- Edits are allowed after Grep has shown the exact lines; overwriting a file with Write still requires a full Read.
|
rigcode-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Sarthak
|
|
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.
|
rigcode-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: rigcode
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A terminal coding agent for models you run yourself: llama.cpp, Ollama, LM Studio, vLLM. Built to stay fast on slow hardware.
|
|
5
|
+
Project-URL: Homepage, https://github.com/sarthak-1111/rigcode
|
|
6
|
+
Project-URL: Issues, https://github.com/sarthak-1111/rigcode/issues
|
|
7
|
+
Project-URL: Changelog, https://github.com/sarthak-1111/rigcode/blob/main/CHANGELOG.md
|
|
8
|
+
Author: Sarthak
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: agent,ai,cli,coding-agent,llama.cpp,llm,local-llm,ollama,self-hosted
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
22
|
+
Classifier: Topic :: Software Development
|
|
23
|
+
Requires-Python: >=3.10
|
|
24
|
+
Requires-Dist: httpx>=0.27
|
|
25
|
+
Requires-Dist: prompt-toolkit>=3.0.43
|
|
26
|
+
Requires-Dist: pyyaml>=6.0
|
|
27
|
+
Requires-Dist: rich>=13.7
|
|
28
|
+
Provides-Extra: dev
|
|
29
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
30
|
+
Requires-Dist: ruff>=0.6; extra == 'dev'
|
|
31
|
+
Description-Content-Type: text/markdown
|
|
32
|
+
|
|
33
|
+
# rigcode
|
|
34
|
+
|
|
35
|
+
**A terminal coding agent for the model on your own rig.**
|
|
36
|
+
|
|
37
|
+
rigcode reads your code, edits files, runs commands and tests, and delegates to subagents, the way commercial coding agents do. The model it uses runs on your hardware: llama.cpp, Ollama, LM Studio, vLLM, SGLang, or any OpenAI-compatible server. Your code never leaves your machines, and rigcode has no telemetry.
|
|
38
|
+
|
|
39
|
+
It is built for the case other agents handle badly: **a big model on modest hardware**. When your server reads prompts at 30 tokens a second, re-reading a 4,000-token conversation costs two minutes, and most agents re-read it on every turn. rigcode is designed around how llama.cpp's prompt cache actually works, so each step re-reads only the new tokens.
|
|
40
|
+
|
|
41
|
+
<!-- Demo GIF goes here: docs/demo.gif -->
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
pipx install rigcode # or: uv tool install rigcode
|
|
45
|
+
cd your-project
|
|
46
|
+
rigcode # finds a local llama.cpp, Ollama, LM Studio or vLLM server on its own
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Why rigcode
|
|
50
|
+
|
|
51
|
+
- **Fast on slow hardware.** The prompt prefix stays fixed for the whole session and the history is append-only, so the server's cache always applies. Subagents fork the cached conversation instead of starting cold. A background warm-up reads the prompt while you type. The details and measurements are below.
|
|
52
|
+
- **Zero setup for local servers.** With no configuration, rigcode checks the default ports of llama.cpp (8080), Ollama (11434), LM Studio (1234) and vLLM/SGLang (8000), and uses the model the server has loaded. `rigcode doctor` explains anything that's wrong, down to the firewall command to run.
|
|
53
|
+
- **A full agent, not a chat window.** Read, Edit, Write, Grep, Glob and Bash tools; background shells; seven built-in subagents; plan mode; a todo list; `/undo`; session resume; web search and fetch.
|
|
54
|
+
- **Safe by default.** It asks before editing files, running commands or using the web. Read-only commands such as `git status` and `ls` run without asking. Allow and deny rules let you tune it per project.
|
|
55
|
+
- **Bring your existing setup.** It reads `AGENTS.md` and `CLAUDE.md`, plus custom commands, agents and skills in `.claude/`. Hooks use the same event names and JSON format, and MCP servers can come from `.mcp.json`. Permission rules use the familiar `Bash(npm test:*)` syntax.
|
|
56
|
+
- **Works with imperfect models.** If the server rejects native tool calls, rigcode falls back to text-based ones. It recovers Kimi-, Hermes- and Qwen-style tool calls that leak into the reply text, and it repairs broken JSON arguments.
|
|
57
|
+
|
|
58
|
+
## Benchmarks
|
|
59
|
+
|
|
60
|
+
Both agents used the same model and server: Kimi K3 (2.78T parameters) on llama.cpp, on one machine on the local network. The tasks are six SWE-bench Verified issues from Django and SymPy, graded with the maintainers' hidden tests at maximum reasoning effort. Every run was audited for internet use and for reading files outside its own checkout.
|
|
61
|
+
|
|
62
|
+
| | rigcode | Claude Code (same model) |
|
|
63
|
+
|---|---|---|
|
|
64
|
+
| Issues resolved, clean runs | **4 / 6** | **4 / 5** |
|
|
65
|
+
| Runs excluded | 0 | 1 (read a later Django release that contains the fix) |
|
|
66
|
+
|
|
67
|
+
On six tasks that's a tie, not a win for either. In an earlier test on five small tasks at low effort, both solved all five, and rigcode took 30% less time (41 vs 59 min) and generated 34% fewer tokens. [Method, per-task results and caveats](docs/benchmarks.md).
|
|
68
|
+
|
|
69
|
+
## Quick start
|
|
70
|
+
|
|
71
|
+
Requires Python 3.10+. Install with `pipx install rigcode`, `uv tool install rigcode`, or `pip install rigcode`.
|
|
72
|
+
|
|
73
|
+
**Ollama**
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
ollama pull gpt-oss:20b # any model that supports tool calling
|
|
77
|
+
OLLAMA_CONTEXT_LENGTH=32768 ollama serve # Ollama's default context is too small for an agent
|
|
78
|
+
rigcode -m gpt-oss:20b
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
**llama.cpp**
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
llama-server -m model.gguf --jinja -c 65536 --port 8080 # --jinja enables tool calling
|
|
85
|
+
rigcode
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
**Any other OpenAI-compatible server**, local or remote:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
rigcode --base-url http://gpu-box:8000/v1 -m qwen3-coder --api-key "$KEY"
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
To make that permanent: `rigcode config set provider.base_url http://gpu-box:8000/v1 --user`.
|
|
95
|
+
|
|
96
|
+
Optional: install [ripgrep](https://github.com/BurntSushi/ripgrep) for faster search. On Windows, rigcode uses Git Bash when it's installed and PowerShell otherwise.
|
|
97
|
+
|
|
98
|
+
## Use
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
rigcode # interactive session in the current project
|
|
102
|
+
rigcode "fix the failing test in tests/test_api.py" # start with a prompt
|
|
103
|
+
rigcode -c # continue the last session here; rigcode -r [id] to pick one
|
|
104
|
+
rigcode -p "explain src/auth.py" --output-format json # headless: run one task and print the result
|
|
105
|
+
git diff | rigcode -p "review this diff" # stdin is appended to the prompt
|
|
106
|
+
rigcode -e high # reasoning effort: low | medium | high | max | none
|
|
107
|
+
rigcode --mode plan # read-only until you approve a plan
|
|
108
|
+
rigcode doctor # diagnose the server connection and local setup
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### Keys and input
|
|
112
|
+
|
|
113
|
+
| Key / input | Action |
|
|
114
|
+
|---|---|
|
|
115
|
+
| Enter | Send. While the agent works, your message is **queued and delivered at its next step**, so you can steer it mid-task. |
|
|
116
|
+
| Alt+Enter, Ctrl+J, `\` + Enter | New line |
|
|
117
|
+
| Esc or Ctrl+C | Interrupt the agent. Ctrl+C twice on an empty prompt (or Ctrl+D) exits. |
|
|
118
|
+
| Shift+Tab | Cycle the permission mode: default → accept edits → plan |
|
|
119
|
+
| Ctrl+O / Ctrl+T | Toggle the full thinking display / the todo list |
|
|
120
|
+
| `@path` | Attach a file or directory listing to your message (Tab completes). This saves the model a tool round trip. |
|
|
121
|
+
| `!command` | Run a shell command yourself; the agent sees the output next turn |
|
|
122
|
+
| `#note` | Append a line to the project's `AGENTS.md` |
|
|
123
|
+
|
|
124
|
+
### Slash commands
|
|
125
|
+
|
|
126
|
+
`/help` `/clear` `/compact [focus]` `/context` `/cost` `/status` `/model [profile]` `/effort [level]` `/mode [mode]` `/plan [task]` `/permissions [allow|deny|ask RULE]` `/add-dir PATH` `/tools` `/agents` `/skills` `/mcp` `/memory` `/init` `/review [focus]` `/commit` `/diff` `/undo` `/todos` `/resume [id]` `/export [path]` `/thinking [collapsed|full|hidden]` `/config [key [value]]` `/doctor` `/bashes` `/exit`
|
|
127
|
+
|
|
128
|
+
Custom commands are Markdown files in `.rigcode/commands/` or `.claude/commands/`. They support `$ARGUMENTS`, `$1`…`$9`, and `` !`cmd` `` when the file's `allowed-tools` includes Bash.
|
|
129
|
+
|
|
130
|
+
## How it stays fast on slow hardware
|
|
131
|
+
|
|
132
|
+
These measurements come from Kimi K3 on llama.cpp, where prompt processing runs at about 10–35 tokens/s and generation at about 5 tokens/s.
|
|
133
|
+
|
|
134
|
+
- **Reuse happens only at checkpoints.** Hybrid models such as Kimi K3 can only rewind the cache to a checkpoint, and llama.cpp makes those at the start of user messages (plus two at the end of each prompt). So rigcode keeps everything before the first user message fixed for the whole session: the tool definitions and one system message with the core prompt and stable project context. Volatile facts (date, git status, recent commits) go in a reminder in your first message, and the history is append-only.
|
|
135
|
+
- **No slot pinning.** With its default unified KV cache, llama.cpp saves every idle slot to a RAM cache and clears the slot when a request starts. Only an unpinned request gets its saved state loaded back, so rigcode lets the server choose the slot. Measured: a 1,052-token prompt was restored in 1.2 s after another slot had been used.
|
|
136
|
+
- **Subagents fork the conversation.** A subagent continues from the main agent's cached prompt, and its brief arrives as the result of the Task call. When it finishes, the main agent continues from the subagent's state, which still begins with the whole main conversation. Measured: the subagent's first request re-read about 500 of 4,147 tokens, and the main agent's next one re-read 124 of 3,770. A subagent starts fresh only when it can't fork (a custom agent with its own model or effort, or a conversation over half the context window).
|
|
137
|
+
- **Background warm-up.** While you type your first message, rigcode processes the prompt prefix, or the whole history after `--continue`. Your first request waits for it rather than racing it on another slot.
|
|
138
|
+
- **Compaction triggers on an absolute token count** (`context.compact_at_tokens`, default 100k). The summary request reuses the cached conversation.
|
|
139
|
+
- **Live progress.** The status line shows prompt processing (`Reading prompt 45% … ~1m 10s left`), thinking, generation speed and tool activity. Read timeouts are never retried automatically, because disconnecting cancels the server's work.
|
|
140
|
+
- Tool output is capped and middle-truncated, with the full output saved to a file. Independent read-only tool calls run in parallel.
|
|
141
|
+
|
|
142
|
+
If you start llama-server with `--no-cache-idle-slots`, idle slots keep their cache in VRAM. You can then set `provider.llama_cpp.slot_pinning: true` to give the main agent and each fresh subagent its own slot.
|
|
143
|
+
|
|
144
|
+
## Permissions
|
|
145
|
+
|
|
146
|
+
Modes: `default` asks before edits, commands and web access. `acceptEdits` auto-approves edits inside the workspace. `plan` is read-only until you approve a plan. `bypass` allows everything except deny rules.
|
|
147
|
+
|
|
148
|
+
Read-only shell commands (`ls`, `git status`, `rg`, …) are approved automatically; anything with output redirection or command substitution asks first. Rules live in `.rigcode/settings.local.json` (personal) or `.rigcode/settings.json` (shared with the repo):
|
|
149
|
+
|
|
150
|
+
```json
|
|
151
|
+
{ "permissions": {
|
|
152
|
+
"allow": ["Bash(npm test:*)", "Bash(python -m pytest:*)", "Edit(src/**)", "WebFetch(domain:docs.python.org)", "mcp__github"],
|
|
153
|
+
"deny": ["Bash(git push:*)", "Read(.env)"],
|
|
154
|
+
"ask": ["Bash(git commit:*)"] } }
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Choosing "don't ask again" in a permission prompt saves the suggested rule. `/undo` reverts the files changed in the last turn.
|
|
158
|
+
|
|
159
|
+
## Configuration
|
|
160
|
+
|
|
161
|
+
Layers, later wins: built-in defaults < `~/.rigcode/settings.json` < `.rigcode/settings.json` < `.rigcode/settings.local.json` < environment (`RIGCODE_BASE_URL`, `RIGCODE_MODEL`, `RIGCODE_API_KEY`, `RIGCODE_EFFORT`, `RIGCODE_CONTEXT_WINDOW`, `RIGCODE_TOOL_MODE`) < command-line flags. `rigcode config` shows the result, and `rigcode config set provider.reasoning_effort high [--user|--project|--local]` changes it.
|
|
162
|
+
|
|
163
|
+
```json
|
|
164
|
+
{
|
|
165
|
+
"provider": {
|
|
166
|
+
"base_url": "auto", "model": "auto", "api_key": "none",
|
|
167
|
+
"reasoning_effort": "low", "max_output_tokens": 32768, "tool_mode": "auto",
|
|
168
|
+
"llama_cpp": { "slot_pinning": false }
|
|
169
|
+
},
|
|
170
|
+
"profiles": { "deep": { "reasoning_effort": "max" }, "gpu-box": { "base_url": "http://gpu-box:8000/v1", "model": "qwen3-coder" } },
|
|
171
|
+
"agents": { "context": "auto", "max_concurrency": 1, "max_turns": 40 },
|
|
172
|
+
"context": { "compact_at_tokens": 100000, "max_tool_output_chars": 12000 },
|
|
173
|
+
"ui": { "thinking": "collapsed", "notify": "bell" }
|
|
174
|
+
}
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Switch profiles with `rigcode -m deep` or `/model gpu-box`. `tool_mode: auto` uses native tool calls and falls back to text-based `<tool_call>` blocks if the server rejects tools.
|
|
178
|
+
|
|
179
|
+
`agents.context` controls how subagents start. `auto` (the default) forks them from the main conversation while it is below `agents.fork_max_tokens` (by default the compaction threshold or half the context window, whichever is smaller) and starts them fresh beyond that. `fork` always forks and `fresh` never does. Parallel subagents (`max_concurrency` above 1) need `fresh`, because parallel forks would each re-read the conversation.
|
|
180
|
+
|
|
181
|
+
## Extending
|
|
182
|
+
|
|
183
|
+
- **Memory:** `AGENTS.md`, `CLAUDE.md` or `RIGCODE.md`, found by walking up from the working directory, plus `~/.rigcode/AGENTS.md`. `@path` imports work. `/init` writes an `AGENTS.md` for you.
|
|
184
|
+
- **Subagents:** seven are built in: `explore`, `plan`, `coder`, `reviewer`, `debugger`, `researcher` and `verifier`. To add your own, put a Markdown file with `name`, `description`, `tools` and optionally `effort`, `max_turns` or `model` (a profile name) frontmatter in `.rigcode/agents/` or `.claude/agents/`.
|
|
185
|
+
- **Skills:** `.rigcode/skills/<name>/SKILL.md` (or `.claude/skills/`). The model sees each skill's description and loads the full instructions when it needs them.
|
|
186
|
+
- **Hooks:** `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `SessionStart`, `SessionEnd` and `PreCompact`. Hooks get JSON on stdin; exit code 2 blocks the action, and stderr is fed back to the model.
|
|
187
|
+
- **MCP servers:** add them under `"mcp_servers"` in settings or in a `.mcp.json`. Both stdio and streamable HTTP work, and tools appear as `mcp__<server>__<tool>`.
|
|
188
|
+
|
|
189
|
+
## Troubleshooting
|
|
190
|
+
|
|
191
|
+
- **`rigcode doctor`** checks the configuration, the shell, TCP reachability, the server type, the context size and slots, and makes a tiny chat request. If the TCP check times out, a firewall is blocking the port; doctor prints the `ufw` command for the server.
|
|
192
|
+
- **The model forgets things or ignores instructions on Ollama:** the context window is probably too small. Ollama's is set with `OLLAMA_CONTEXT_LENGTH`; rigcode needs at least 16k tokens, and 32k or more is better. rigcode warns when it detects a small window.
|
|
193
|
+
- **`rigcode --debug`** logs a summary of every request and response, including prompt and cached token counts, to `~/.rigcode/logs/<session>.jsonl`.
|
|
194
|
+
- **The first session after a change is slower.** Changing anything in the prompt prefix means it gets re-read once: upgrading rigcode, adding an MCP server, agent or skill, editing a memory file, changing effort, or adding a top-level directory. Later sessions in the same project reuse it.
|
|
195
|
+
- Sessions are stored as append-only JSONL in `~/.rigcode/projects/<project>/` and survive crashes. `rigcode sessions` lists them.
|
|
196
|
+
|
|
197
|
+
## Contributing
|
|
198
|
+
|
|
199
|
+
Bug reports with `rigcode doctor` output are the most useful thing you can send. See [CONTRIBUTING.md](CONTRIBUTING.md) for the development setup.
|
|
200
|
+
|
|
201
|
+
## License
|
|
202
|
+
|
|
203
|
+
[MIT](LICENSE)
|
rigcode-0.1.0/README.md
ADDED
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
# rigcode
|
|
2
|
+
|
|
3
|
+
**A terminal coding agent for the model on your own rig.**
|
|
4
|
+
|
|
5
|
+
rigcode reads your code, edits files, runs commands and tests, and delegates to subagents, the way commercial coding agents do. The model it uses runs on your hardware: llama.cpp, Ollama, LM Studio, vLLM, SGLang, or any OpenAI-compatible server. Your code never leaves your machines, and rigcode has no telemetry.
|
|
6
|
+
|
|
7
|
+
It is built for the case other agents handle badly: **a big model on modest hardware**. When your server reads prompts at 30 tokens a second, re-reading a 4,000-token conversation costs two minutes, and most agents re-read it on every turn. rigcode is designed around how llama.cpp's prompt cache actually works, so each step re-reads only the new tokens.
|
|
8
|
+
|
|
9
|
+
<!-- Demo GIF goes here: docs/demo.gif -->
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
pipx install rigcode # or: uv tool install rigcode
|
|
13
|
+
cd your-project
|
|
14
|
+
rigcode # finds a local llama.cpp, Ollama, LM Studio or vLLM server on its own
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Why rigcode
|
|
18
|
+
|
|
19
|
+
- **Fast on slow hardware.** The prompt prefix stays fixed for the whole session and the history is append-only, so the server's cache always applies. Subagents fork the cached conversation instead of starting cold. A background warm-up reads the prompt while you type. The details and measurements are below.
|
|
20
|
+
- **Zero setup for local servers.** With no configuration, rigcode checks the default ports of llama.cpp (8080), Ollama (11434), LM Studio (1234) and vLLM/SGLang (8000), and uses the model the server has loaded. `rigcode doctor` explains anything that's wrong, down to the firewall command to run.
|
|
21
|
+
- **A full agent, not a chat window.** Read, Edit, Write, Grep, Glob and Bash tools; background shells; seven built-in subagents; plan mode; a todo list; `/undo`; session resume; web search and fetch.
|
|
22
|
+
- **Safe by default.** It asks before editing files, running commands or using the web. Read-only commands such as `git status` and `ls` run without asking. Allow and deny rules let you tune it per project.
|
|
23
|
+
- **Bring your existing setup.** It reads `AGENTS.md` and `CLAUDE.md`, plus custom commands, agents and skills in `.claude/`. Hooks use the same event names and JSON format, and MCP servers can come from `.mcp.json`. Permission rules use the familiar `Bash(npm test:*)` syntax.
|
|
24
|
+
- **Works with imperfect models.** If the server rejects native tool calls, rigcode falls back to text-based ones. It recovers Kimi-, Hermes- and Qwen-style tool calls that leak into the reply text, and it repairs broken JSON arguments.
|
|
25
|
+
|
|
26
|
+
## Benchmarks
|
|
27
|
+
|
|
28
|
+
Both agents used the same model and server: Kimi K3 (2.78T parameters) on llama.cpp, on one machine on the local network. The tasks are six SWE-bench Verified issues from Django and SymPy, graded with the maintainers' hidden tests at maximum reasoning effort. Every run was audited for internet use and for reading files outside its own checkout.
|
|
29
|
+
|
|
30
|
+
| | rigcode | Claude Code (same model) |
|
|
31
|
+
|---|---|---|
|
|
32
|
+
| Issues resolved, clean runs | **4 / 6** | **4 / 5** |
|
|
33
|
+
| Runs excluded | 0 | 1 (read a later Django release that contains the fix) |
|
|
34
|
+
|
|
35
|
+
On six tasks that's a tie, not a win for either. In an earlier test on five small tasks at low effort, both solved all five, and rigcode took 30% less time (41 vs 59 min) and generated 34% fewer tokens. [Method, per-task results and caveats](docs/benchmarks.md).
|
|
36
|
+
|
|
37
|
+
## Quick start
|
|
38
|
+
|
|
39
|
+
Requires Python 3.10+. Install with `pipx install rigcode`, `uv tool install rigcode`, or `pip install rigcode`.
|
|
40
|
+
|
|
41
|
+
**Ollama**
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
ollama pull gpt-oss:20b # any model that supports tool calling
|
|
45
|
+
OLLAMA_CONTEXT_LENGTH=32768 ollama serve # Ollama's default context is too small for an agent
|
|
46
|
+
rigcode -m gpt-oss:20b
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
**llama.cpp**
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
llama-server -m model.gguf --jinja -c 65536 --port 8080 # --jinja enables tool calling
|
|
53
|
+
rigcode
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
**Any other OpenAI-compatible server**, local or remote:
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
rigcode --base-url http://gpu-box:8000/v1 -m qwen3-coder --api-key "$KEY"
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
To make that permanent: `rigcode config set provider.base_url http://gpu-box:8000/v1 --user`.
|
|
63
|
+
|
|
64
|
+
Optional: install [ripgrep](https://github.com/BurntSushi/ripgrep) for faster search. On Windows, rigcode uses Git Bash when it's installed and PowerShell otherwise.
|
|
65
|
+
|
|
66
|
+
## Use
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
rigcode # interactive session in the current project
|
|
70
|
+
rigcode "fix the failing test in tests/test_api.py" # start with a prompt
|
|
71
|
+
rigcode -c # continue the last session here; rigcode -r [id] to pick one
|
|
72
|
+
rigcode -p "explain src/auth.py" --output-format json # headless: run one task and print the result
|
|
73
|
+
git diff | rigcode -p "review this diff" # stdin is appended to the prompt
|
|
74
|
+
rigcode -e high # reasoning effort: low | medium | high | max | none
|
|
75
|
+
rigcode --mode plan # read-only until you approve a plan
|
|
76
|
+
rigcode doctor # diagnose the server connection and local setup
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### Keys and input
|
|
80
|
+
|
|
81
|
+
| Key / input | Action |
|
|
82
|
+
|---|---|
|
|
83
|
+
| Enter | Send. While the agent works, your message is **queued and delivered at its next step**, so you can steer it mid-task. |
|
|
84
|
+
| Alt+Enter, Ctrl+J, `\` + Enter | New line |
|
|
85
|
+
| Esc or Ctrl+C | Interrupt the agent. Ctrl+C twice on an empty prompt (or Ctrl+D) exits. |
|
|
86
|
+
| Shift+Tab | Cycle the permission mode: default → accept edits → plan |
|
|
87
|
+
| Ctrl+O / Ctrl+T | Toggle the full thinking display / the todo list |
|
|
88
|
+
| `@path` | Attach a file or directory listing to your message (Tab completes). This saves the model a tool round trip. |
|
|
89
|
+
| `!command` | Run a shell command yourself; the agent sees the output next turn |
|
|
90
|
+
| `#note` | Append a line to the project's `AGENTS.md` |
|
|
91
|
+
|
|
92
|
+
### Slash commands
|
|
93
|
+
|
|
94
|
+
`/help` `/clear` `/compact [focus]` `/context` `/cost` `/status` `/model [profile]` `/effort [level]` `/mode [mode]` `/plan [task]` `/permissions [allow|deny|ask RULE]` `/add-dir PATH` `/tools` `/agents` `/skills` `/mcp` `/memory` `/init` `/review [focus]` `/commit` `/diff` `/undo` `/todos` `/resume [id]` `/export [path]` `/thinking [collapsed|full|hidden]` `/config [key [value]]` `/doctor` `/bashes` `/exit`
|
|
95
|
+
|
|
96
|
+
Custom commands are Markdown files in `.rigcode/commands/` or `.claude/commands/`. They support `$ARGUMENTS`, `$1`…`$9`, and `` !`cmd` `` when the file's `allowed-tools` includes Bash.
|
|
97
|
+
|
|
98
|
+
## How it stays fast on slow hardware
|
|
99
|
+
|
|
100
|
+
These measurements come from Kimi K3 on llama.cpp, where prompt processing runs at about 10–35 tokens/s and generation at about 5 tokens/s.
|
|
101
|
+
|
|
102
|
+
- **Reuse happens only at checkpoints.** Hybrid models such as Kimi K3 can only rewind the cache to a checkpoint, and llama.cpp makes those at the start of user messages (plus two at the end of each prompt). So rigcode keeps everything before the first user message fixed for the whole session: the tool definitions and one system message with the core prompt and stable project context. Volatile facts (date, git status, recent commits) go in a reminder in your first message, and the history is append-only.
|
|
103
|
+
- **No slot pinning.** With its default unified KV cache, llama.cpp saves every idle slot to a RAM cache and clears the slot when a request starts. Only an unpinned request gets its saved state loaded back, so rigcode lets the server choose the slot. Measured: a 1,052-token prompt was restored in 1.2 s after another slot had been used.
|
|
104
|
+
- **Subagents fork the conversation.** A subagent continues from the main agent's cached prompt, and its brief arrives as the result of the Task call. When it finishes, the main agent continues from the subagent's state, which still begins with the whole main conversation. Measured: the subagent's first request re-read about 500 of 4,147 tokens, and the main agent's next one re-read 124 of 3,770. A subagent starts fresh only when it can't fork (a custom agent with its own model or effort, or a conversation over half the context window).
|
|
105
|
+
- **Background warm-up.** While you type your first message, rigcode processes the prompt prefix, or the whole history after `--continue`. Your first request waits for it rather than racing it on another slot.
|
|
106
|
+
- **Compaction triggers on an absolute token count** (`context.compact_at_tokens`, default 100k). The summary request reuses the cached conversation.
|
|
107
|
+
- **Live progress.** The status line shows prompt processing (`Reading prompt 45% … ~1m 10s left`), thinking, generation speed and tool activity. Read timeouts are never retried automatically, because disconnecting cancels the server's work.
|
|
108
|
+
- Tool output is capped and middle-truncated, with the full output saved to a file. Independent read-only tool calls run in parallel.
|
|
109
|
+
|
|
110
|
+
If you start llama-server with `--no-cache-idle-slots`, idle slots keep their cache in VRAM. You can then set `provider.llama_cpp.slot_pinning: true` to give the main agent and each fresh subagent its own slot.
|
|
111
|
+
|
|
112
|
+
## Permissions
|
|
113
|
+
|
|
114
|
+
Modes: `default` asks before edits, commands and web access. `acceptEdits` auto-approves edits inside the workspace. `plan` is read-only until you approve a plan. `bypass` allows everything except deny rules.
|
|
115
|
+
|
|
116
|
+
Read-only shell commands (`ls`, `git status`, `rg`, …) are approved automatically; anything with output redirection or command substitution asks first. Rules live in `.rigcode/settings.local.json` (personal) or `.rigcode/settings.json` (shared with the repo):
|
|
117
|
+
|
|
118
|
+
```json
|
|
119
|
+
{ "permissions": {
|
|
120
|
+
"allow": ["Bash(npm test:*)", "Bash(python -m pytest:*)", "Edit(src/**)", "WebFetch(domain:docs.python.org)", "mcp__github"],
|
|
121
|
+
"deny": ["Bash(git push:*)", "Read(.env)"],
|
|
122
|
+
"ask": ["Bash(git commit:*)"] } }
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Choosing "don't ask again" in a permission prompt saves the suggested rule. `/undo` reverts the files changed in the last turn.
|
|
126
|
+
|
|
127
|
+
## Configuration
|
|
128
|
+
|
|
129
|
+
Layers, later wins: built-in defaults < `~/.rigcode/settings.json` < `.rigcode/settings.json` < `.rigcode/settings.local.json` < environment (`RIGCODE_BASE_URL`, `RIGCODE_MODEL`, `RIGCODE_API_KEY`, `RIGCODE_EFFORT`, `RIGCODE_CONTEXT_WINDOW`, `RIGCODE_TOOL_MODE`) < command-line flags. `rigcode config` shows the result, and `rigcode config set provider.reasoning_effort high [--user|--project|--local]` changes it.
|
|
130
|
+
|
|
131
|
+
```json
|
|
132
|
+
{
|
|
133
|
+
"provider": {
|
|
134
|
+
"base_url": "auto", "model": "auto", "api_key": "none",
|
|
135
|
+
"reasoning_effort": "low", "max_output_tokens": 32768, "tool_mode": "auto",
|
|
136
|
+
"llama_cpp": { "slot_pinning": false }
|
|
137
|
+
},
|
|
138
|
+
"profiles": { "deep": { "reasoning_effort": "max" }, "gpu-box": { "base_url": "http://gpu-box:8000/v1", "model": "qwen3-coder" } },
|
|
139
|
+
"agents": { "context": "auto", "max_concurrency": 1, "max_turns": 40 },
|
|
140
|
+
"context": { "compact_at_tokens": 100000, "max_tool_output_chars": 12000 },
|
|
141
|
+
"ui": { "thinking": "collapsed", "notify": "bell" }
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Switch profiles with `rigcode -m deep` or `/model gpu-box`. `tool_mode: auto` uses native tool calls and falls back to text-based `<tool_call>` blocks if the server rejects tools.
|
|
146
|
+
|
|
147
|
+
`agents.context` controls how subagents start. `auto` (the default) forks them from the main conversation while it is below `agents.fork_max_tokens` (by default the compaction threshold or half the context window, whichever is smaller) and starts them fresh beyond that. `fork` always forks and `fresh` never does. Parallel subagents (`max_concurrency` above 1) need `fresh`, because parallel forks would each re-read the conversation.
|
|
148
|
+
|
|
149
|
+
## Extending
|
|
150
|
+
|
|
151
|
+
- **Memory:** `AGENTS.md`, `CLAUDE.md` or `RIGCODE.md`, found by walking up from the working directory, plus `~/.rigcode/AGENTS.md`. `@path` imports work. `/init` writes an `AGENTS.md` for you.
|
|
152
|
+
- **Subagents:** seven are built in: `explore`, `plan`, `coder`, `reviewer`, `debugger`, `researcher` and `verifier`. To add your own, put a Markdown file with `name`, `description`, `tools` and optionally `effort`, `max_turns` or `model` (a profile name) frontmatter in `.rigcode/agents/` or `.claude/agents/`.
|
|
153
|
+
- **Skills:** `.rigcode/skills/<name>/SKILL.md` (or `.claude/skills/`). The model sees each skill's description and loads the full instructions when it needs them.
|
|
154
|
+
- **Hooks:** `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `SessionStart`, `SessionEnd` and `PreCompact`. Hooks get JSON on stdin; exit code 2 blocks the action, and stderr is fed back to the model.
|
|
155
|
+
- **MCP servers:** add them under `"mcp_servers"` in settings or in a `.mcp.json`. Both stdio and streamable HTTP work, and tools appear as `mcp__<server>__<tool>`.
|
|
156
|
+
|
|
157
|
+
## Troubleshooting
|
|
158
|
+
|
|
159
|
+
- **`rigcode doctor`** checks the configuration, the shell, TCP reachability, the server type, the context size and slots, and makes a tiny chat request. If the TCP check times out, a firewall is blocking the port; doctor prints the `ufw` command for the server.
|
|
160
|
+
- **The model forgets things or ignores instructions on Ollama:** the context window is probably too small. Ollama's is set with `OLLAMA_CONTEXT_LENGTH`; rigcode needs at least 16k tokens, and 32k or more is better. rigcode warns when it detects a small window.
|
|
161
|
+
- **`rigcode --debug`** logs a summary of every request and response, including prompt and cached token counts, to `~/.rigcode/logs/<session>.jsonl`.
|
|
162
|
+
- **The first session after a change is slower.** Changing anything in the prompt prefix means it gets re-read once: upgrading rigcode, adding an MCP server, agent or skill, editing a memory file, changing effort, or adding a top-level directory. Later sessions in the same project reuse it.
|
|
163
|
+
- Sessions are stored as append-only JSONL in `~/.rigcode/projects/<project>/` and survive crashes. `rigcode sessions` lists them.
|
|
164
|
+
|
|
165
|
+
## Contributing
|
|
166
|
+
|
|
167
|
+
Bug reports with `rigcode doctor` output are the most useful thing you can send. See [CONTRIBUTING.md](CONTRIBUTING.md) for the development setup.
|
|
168
|
+
|
|
169
|
+
## License
|
|
170
|
+
|
|
171
|
+
[MIT](LICENSE)
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.21"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "rigcode"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "A terminal coding agent for models you run yourself: llama.cpp, Ollama, LM Studio, vLLM. Built to stay fast on slow hardware."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
authors = [{ name = "Sarthak" }]
|
|
13
|
+
requires-python = ">=3.10"
|
|
14
|
+
keywords = ["coding-agent", "llm", "local-llm", "llama.cpp", "ollama", "self-hosted", "cli", "agent", "ai"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 4 - Beta",
|
|
17
|
+
"Environment :: Console",
|
|
18
|
+
"Intended Audience :: Developers",
|
|
19
|
+
"Operating System :: OS Independent",
|
|
20
|
+
"Programming Language :: Python :: 3",
|
|
21
|
+
"Programming Language :: Python :: 3.10",
|
|
22
|
+
"Programming Language :: Python :: 3.11",
|
|
23
|
+
"Programming Language :: Python :: 3.12",
|
|
24
|
+
"Programming Language :: Python :: 3.13",
|
|
25
|
+
"Topic :: Software Development",
|
|
26
|
+
"Topic :: Scientific/Engineering :: Artificial Intelligence",
|
|
27
|
+
]
|
|
28
|
+
dependencies = [
|
|
29
|
+
"httpx>=0.27",
|
|
30
|
+
"rich>=13.7",
|
|
31
|
+
"prompt_toolkit>=3.0.43",
|
|
32
|
+
"pyyaml>=6.0",
|
|
33
|
+
]
|
|
34
|
+
|
|
35
|
+
[project.optional-dependencies]
|
|
36
|
+
dev = ["pytest>=8", "ruff>=0.6"]
|
|
37
|
+
|
|
38
|
+
[project.urls]
|
|
39
|
+
Homepage = "https://github.com/sarthak-1111/rigcode"
|
|
40
|
+
Issues = "https://github.com/sarthak-1111/rigcode/issues"
|
|
41
|
+
Changelog = "https://github.com/sarthak-1111/rigcode/blob/main/CHANGELOG.md"
|
|
42
|
+
|
|
43
|
+
[project.scripts]
|
|
44
|
+
rigcode = "rigcode.cli:main"
|
|
45
|
+
|
|
46
|
+
[tool.hatch.build.targets.wheel]
|
|
47
|
+
packages = ["rigcode"]
|
|
48
|
+
|
|
49
|
+
[tool.hatch.build.targets.sdist]
|
|
50
|
+
include = ["rigcode", "tests", "README.md", "LICENSE", "CHANGELOG.md", "pyproject.toml"]
|
|
51
|
+
|
|
52
|
+
[tool.pytest.ini_options]
|
|
53
|
+
testpaths = ["tests"]
|
|
54
|
+
|
|
55
|
+
[tool.ruff]
|
|
56
|
+
line-length = 120
|
|
57
|
+
target-version = "py310"
|
|
58
|
+
|
|
59
|
+
[tool.ruff.lint]
|
|
60
|
+
select = ["E", "F", "W", "I", "B", "UP"]
|
|
61
|
+
ignore = ["E501", "E741", "B905"] # B905: zipped lists are equal-length by construction (gather results)
|
|
File without changes
|