fischerj
/
jcode
1
1
Fork 1
Code Issues 3 Pull Requests Packages Projects Releases Wiki Activity

Readme auf multimodales jcode angepasst

multimodal
Jörn Fischer 2026-09-23 12:00:08 +02:00
parent b0c3d32e3f
commit b37d004cb7
1 changed files with 27 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
README.md
View File

@ -1,8 +1,8 @@
# jcode
A minimal, single-file coding agent (< 1000 lines of Python) for local LLMs — with optional cloud fallback.
A minimal, single-file coding agent (~1,200 lines of Python) for local LLMs — with optional cloud fallback.
jcode connects to a local **LM Studio** or **Ollama** server (or, via `settings.json`, to **OpenAI**, **Anthropic**, or **Gemini**), takes a task in plain language, and works autonomously inside a sandboxed `./code` directory: it reads, writes, and edits files, runs commands, writes its own smoke tests, and keeps fixing the code until the tests pass.
jcode connects to a local **LM Studio** or **Ollama** server (or, via `settings.json`, to **OpenAI**, **Anthropic**, or **Gemini**), takes a task in plain language, and works autonomously inside a sandboxed `./code` directory: it reads, writes, and edits files, runs commands, searches the web, looks at images/screenshots/PDF pages, writes its own smoke tests, and keeps fixing the code until the tests pass.
```
_ _
@ -15,15 +15,22 @@ jcode connects to a local **LM Studio** or **Ollama** server (or, via `settings.
## Features
- **Autonomous test-fix loop** — the agent writes a test for every change, runs it, analyzes failures, fixes the code, and repeats until green (up to `MAX_STEPS`, default 40).
- **Autonomous test-fix loop** — the agent writes a test for every change, runs it, analyzes failures, fixes the code, and repeats until green (up to `MAX_STEPS`, default 200).
- **Sandboxed** — all file operations are confined to `./code`; path-escape attempts (`../`, absolute paths) are blocked. Destructive shell commands (`rm -rf /`, `sudo`, `dd`, `mkfs`, shutdown, fork bombs, `curl | sh`, …) are refused.
- **Zero-config local backends** — auto-detects LM Studio (port 1234) first, then Ollama (port 11434).
- **Cloud providers via `settings.json`** — switch to OpenAI, Anthropic, or Gemini at runtime with `/backend <name>`; all are used through their OpenAI-compatible endpoints, so the single `openai` client dependency covers everything.
- **Project guidelines via `AGENTS.md`** — project-specific rules (coding style, per-language test conventions) are loaded from `code/AGENTS.md` and injected as binding instructions.
- **Vision** — the agent can look at images, screenshots and PDF pages (see the `view_image`/`take_screenshot`/`view_pdf_page` tools below) to visually check its own work, e.g. a generated plot or a running GUI.
- **Session-wide context management** — token usage is tracked (server-reported or estimated); when the context nears its limit, older history is compacted into an LLM-written summary so long sessions keep working.
- **Adjustable reasoning effort** — `/reasoning high|medium|low|max|none` controls the model's thinking effort at runtime (backend-dependent; `none` turns it off).
- **Robust against flaky servers** — visible retries with backoff; if the backend goes down, the session is preserved and the task can simply be resubmitted.
- **Transparent** — every request, tool call, and result is logged to `logFile.md`; file changes are shown as colored unified diffs in the terminal.
- **Tools available to the model** — `list_files`, `read_file` (optionally with line numbers), `search_files` (regex grep over the sandbox, hits as `file:line: content`), `write_file`, `edit_file` (search/replace), `insert_lines`, `delete_lines`, `run_command`, `web_search` (DuckDuckGo), `fetch_url`.
- **Tools available to the model:**
- `list_files`, `read_file` (optionally with line numbers), `search_files` (regex grep over the sandbox, hits as `file:line: content`)
- `write_file`, `edit_file` (search/replace), `insert_lines`, `delete_lines`
- `run_command` (blocks known-destructive patterns; `pip`/`pip3` calls are redirected to jcode's own Python interpreter)
- `web_search` (DuckDuckGo) and `fetch_url` (fetches a page and extracts its text)
- `view_image` (png/jpg/gif/webp/bmp/svg), `take_screenshot` (whole screen, e.g. of a GUI app under test), `view_pdf_page` (renders one PDF page) — images are delivered to the model as an inline image right after the tool result
## Requirements
@ -33,6 +40,11 @@ jcode connects to a local **LM Studio** or **Ollama** server (or, via `settings.
- [LM Studio](https://lmstudio.ai/) with the local server running (default `http://localhost:1234`), or
- [Ollama](https://ollama.com/) (`http://localhost:11434`), or
- an API key for OpenAI / Anthropic / Gemini (see `settings.json` below)
- Optional, only needed for the vision tools (the agent will tell you what's missing and how to install it when it tries to use one):
- `Pillow` — `view_image`, `take_screenshot`, `view_pdf_page`
- `cairosvg` — `view_image` on `.svg` files
- `pymupdf` — `view_pdf_page`
- `certifi` — CA bundle for `fetch_url`; falls back to the system default if not installed. Set `JCODE_INSECURE_SSL=1` to disable TLS verification (e.g. behind a re-signing corporate proxy) — use with care.
## Usage
@ -55,8 +67,10 @@ All generated files land in `./code`, which is created automatically.
| `/models` | List models available on the current backend |
| `/model <name>` | Switch model |
| `/backend <name>` | Switch to `lm-studio`, `ollama`, or a provider from `settings.json` (e.g. `openai`, `anthropic`, `gemini`) |
| `/reasoning <level>` | Set reasoning effort: `high`, `medium`, `low`, `max`, or `none` (off); no argument resets to the backend default |
| `/max-turns N` | Set the step limit per task |
| `Ctrl+C` | Quit |
| `Ctrl+C` | Abort the current input or running task (session is preserved) |
| `Ctrl+D`, or `Ctrl+C` on an empty prompt | Quit |
## Configuration
@ -105,12 +119,16 @@ If `code/AGENTS.md` exists, it is loaded at session start and treated as binding
| Constant | Default | Meaning |
|---|---|---|
| `MODEL` | (auto) | Model name; auto-corrected to the first available model |
| `MAX_STEPS` | 40 | Tool-use steps per task |
| `CMD_TIMEOUT` | 60 s | Timeout per shell command |
| `MODEL` | (auto) | Model name; auto-corrected to the closest available model |
| `MAX_STEPS` | 200 | Tool-use steps per task |
| `CMD_TIMEOUT` | 60 s | Default timeout per shell command (overridable per call via the `timeout` argument) |
| `CONTEXT_LIMIT` | 256 000 | Model context window (tokens) |
| `COMPACT_THRESHOLD` | 250 000 | History compaction kicks in above this |
| `REQUEST_TIMEOUT` | 600 s | Timeout per LLM request (local models are slow) |
| `KEEP_RECENT` | 8 | Most recent messages kept uncompressed when compacting |
| `REQUEST_TIMEOUT` | 11 600 s | Timeout per LLM request (local models are slow) |
| `REASONING_EFFORT` | (backend default) | Reasoning effort sent to the backend; set at runtime with `/reasoning` |
| `MAX_IMAGE_SIDE` | 1280 px | Longest edge images are scaled to before being sent to the model |
| `MAX_IMAGES_IN_CONTEXT` | 4 | Older images beyond this are replaced by a text stub to save context |
## How it works