AGENT8088

<p align="center"> <img src="assets/palindrome-research-labs-agent8088.png" alt="Palindrome Research Labs" width="294"> <br> <img src="assets/agent8088-wordmark-readme.png" alt="Agent8088" width="540"> </p> <p align="center"> <strong>Reliable AI agents&mdash;even on small, local models.</strong> </p> <p align="center"> <a href="#about">About</a> · <a href="#quick-start">Quick start</a> · <a href="#inside-agent8088">Features</a> · <a href="#documentation">Documentation</a> · <a href="https://palindromerl.com/blog/agent8088-agentic-harness">Blog</a> · <a href="#contributing">Contributing</a> </p> <p align="center"> <a href="https://github.com/palindrome-rl/AGENT8088/actions/workflows/ci.yml"><img src="https://github.com/palindrome-rl/AGENT8088/actions/workflows/ci.yml/badge.svg?branch=AGENT8088-v1.3" alt="CI status"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a> <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+"></a> <a href="https://github.com/palindrome-rl/AGENT8088/tree/AGENT8088-v1.3"><img src="https://img.shields.io/badge/release-v1.3-f59e0b" alt="Agent8088 v1.3 branch"></a> <img src="https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey" alt="macOS, Linux, Windows"> <img src="https://img.shields.io/badge/MCP-client%20%2B%20server-8b5cf6" alt="MCP client and server"> </p> <p align="center"> <img src="https://img.shields.io/badge/59%20built--in%20tools-execution%20grounded-10b981" alt="59 built-in tools"> <img src="https://img.shields.io/badge/verification--gated%20completion-optional%20audit%20%2B%20rollback-059669" alt="Verification-gated completion"> <img src="https://img.shields.io/badge/6%20sub--agent%20profiles-context%20isolation-3b82f6" alt="6 sub-agent profiles"> <img src="https://img.shields.io/badge/39%20skill%20packages-extensible-6366f1" alt="39 skill packages"> <img src="https://img.shields.io/badge/12%20provider%20profiles-any%20OpenAI--compatible-8b5cf6" alt="12 provider profiles"> <img src="https://img.shields.io/badge/messaging-Slack%20%7C%20Discord%20%7C%20WhatsApp%20%7C%20Telegram%20%7C%20email-f43f5e" alt="Slack, Discord, WhatsApp, Telegram, email"> <img src="https://img.shields.io/badge/local%20OCR-vision--free%20image%20reading-a3a3a3" alt="Local OCR"> </p> <p align="center"> <a href="assets/demo.mp4"> <img src="assets/demo.gif" alt="Agent8088: reliable AI agents, even on small local models. Context budgeting, tool-call repair, permissions and sandboxing, and every front end from one engine." width="820"> </a> </p>

About

Agent8088 is an open-source agentic harness from Palindrome Research Labs, built to make small local models finish real agentic tasks reliably.

Most harnesses assume a large model and trust whatever it reports. Agent8088 fixes the limitations and failure modes of small models through research-backed harness engineering.

Small models mostly fail in specific ways. Their context overflows without warning, their tool calls are malformed or wrongly chosen, they say they are done when they are not, and long runs end up looping or losing progress.

Agent8088 handles these areas around the model through Context Management, Tool Intelligence, Verification-Gated Completion, Grounded Execution, a Reliable Control Loop, Failure Recovery and code-enforced safety. Bigger models mostly show similar failures but less often, so it helps them too.

Apart from focusing on small models reliability, Agent8088 is a complete agentic harness, with broad tooling, web research, documents, MCP, sub-agents, memory and a choice of terminal, web and chat front ends.

<table> <tr> <td width="33%" valign="top"> <strong>Small-model-first</strong><br> _{Efficient prompts, minimized tool schemas, model-aware routing, and local-model support make capable local models practical.} </td> <td width="33%" valign="top"> <strong>Tool intelligence</strong><br> _{Hybrid tool selection, tolerant call parsing, validated arguments, shaped tool results, and lazy-loaded skills help models choose and use the right tools.} </td> <td width="33%" valign="top"> <strong>Robust context management</strong><br> _{Pre-call token budgeting, overflow prevention, compaction that keeps your instructions word for word, content handles, and persistent task state preserve what matters within the window.} </td> </tr> <tr> <td width="33%" valign="top"> <strong>Verification-gated completion</strong><br> _{Tasks are checked against their required outputs, tests, and observable tool results before completion is reported, with honest verification labels and an optional independent audit.} </td> <td width="33%" valign="top"> <strong>Grounded execution</strong><br> _{Work proceeds through structured tools and observable results, so each step is checked against real files, test output, and system state rather than the model's own claims.} </td> <td width="33%" valign="top"> <strong>Reliable control loop</strong><br> _{A persistent loop plans, acts, and observes, detects repeats and stalls, replans after failures, enforces time and round limits, and escalates to a stronger model only when needed to keep runs moving.} </td> </tr> <tr> <td width="33%" valign="top"> <strong>Failure recovery</strong><br> _{Rollback of failed file changes, resumable tasks, overflow and cut-off retries, and halting at the first failed step keep long runs recoverable.} </td> <td width="33%" valign="top"> <strong>Transparent, safe and controlled</strong><br> _{Permission modes, usage and cost monitoring, audit trails, credential protection, SSRF and egress security controls, and OS-level sandboxing keep actions accountable.} </td> <td width="33%" valign="top"> <strong>Low-friction and extensible</strong><br> _{Use the CLI or web UI, connect local or hosted models, and extend the harness through MCP, skills, sub-agents, and gateways.} </td> </tr> </table> <p align="center"> <img src="assets/failure-loop.jpg" alt="Agent8088 failure categories mapped onto one turn of the agent loop, with the pillars that address each one" width="900"> </p>

Read the full write-up: Agent8088: Agentic Harness for Reliable AI Agents, even on small, local models

---

What's new in v1.3

• Task completion: each part of a request is checked against delivered output; smoke tests separate "could not start here" from real crashes.
• Verification you can read: each answer says how well its changes were checked (tested, only run, or failed), and a failing check shows as NOT VERIFIED at the top.
• Long-running tasks: time and round budget warnings, stall decisions, and your rules kept word for word through compaction.
• Credential safety: secret scanning on pasted text and written files; attachments isolated per session.
• File handling: byte-exact copy_file and move_file; a generated project stays in one folder, and a folder you ask to put in artifacts/ goes there.

Includes the v1.2 reliability fixes; existing configuration and memory are preserved. See the CHANGELOG.

Quick start

Install Agent8088 v1.3

The commands below install the public v1.3 branch. agent8088 --update continues to use this branch.

macOS, Linux, or WSL2

curl -fsSL --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/palindrome-rl/AGENT8088/AGENT8088-v1.3/install.sh | AGENT8088_BRANCH=AGENT8088-v1.3 bash

Windows (PowerShell)

$env:AGENT8088_BRANCH = "AGENT8088-v1.3"; iex (irm https://raw.githubusercontent.com/palindrome-rl/AGENT8088/AGENT8088-v1.3/install.ps1)

Use these branch-specific installers for v1.3; the generic Pages installer may track a different release.

Run the Windows command in PowerShell, not Command Prompt. On macOS/Linux, run as your normal user, without sudo; the installer asks for elevated access only when a system component needs it.

If Windows Terminal cannot be installed or launched, you can install in the current PowerShell window by setting $env:AGENT8088_SKIP_TERMINAL_CHECK = "1" and rerunning the Windows command above. This skips only the terminal-host check; it does not disable antivirus or change execution policy. Windows Terminal remains the supported host for the best display.

The installer provisions an isolated Python environment, installs the global agent8088 command, and can run the setup wizard. No administrator access is required for the base install.

<details> <summary><b>What the installer provisions, and supported platforms</b></summary>

What the installer provisions automatically:

| Component | Linux / macOS | Windows | | --- | --- | --- | | Core agent (chat, tools, MCP, search) | yes | yes | | Gateway adapters (Slack, Discord, WhatsApp, Telegram) | yes | yes | | Playwright Chromium (browse_page) | yes | yes | | Node.js 22 + WhatsApp bridge npm deps | yes | yes (portable, no admin) | | Native sandbox runtime | yes (auto-setup) | yes (auto-setup, no admin needed) |

Supported platforms

| Platform | Status | Notes | |---|---|---| | macOS 12+ (Apple Silicon & Intel) | Supported | install.sh | | Ubuntu / Debian / Fedora / Arch (x64, arm64) | Supported | install.sh | | WSL2 | Supported | install.sh; clone with LF line endings, not CRLF | | Windows 10 (1903+) / 11, in Windows Terminal | Supported | install.ps1 | | Windows Server, legacy Console Host, PowerShell ISE | Not supported | needs a modern terminal host — see install.ps1's terminal check | | Alpine / other non-glibc Linux | Best-effort | works if bash, curl-or-wget, and Python 3.10+ are present | | Corporate proxy (HTTP_PROXY/HTTPS_PROXY) | Supported | both installers honor standard proxy env vars |

</details>

After installing, start agent8088 and run /doctor [--fix] to verify your setup, or /dump to produce a bundle for a bug report.

If installation fails, the installer reports the failed step, keeps its output, and prints a retry command. Logs are saved to %LOCALAPPDATA%\agent8088\install.log on Windows or ~/.agent8088/install.log on macOS/Linux (under AGENT8088_HOME when set). Rerun the same command to resume; optional failures are listed separately from core startup failures. See installation troubleshooting.

The Windows installer verifies dependencies by running their executables, importing installed Python/Node packages, checking Chromium and OCR resources, and validating WebUI assets. A stale resume marker or partial dependency folder triggers repair instead of being treated as success.

The installers do not add the [dev] extra (pytest, ruff, pip-audit). It is not needed to install or run Agent8088.

---

Configure and run

agent8088 --setup            # choose a provider, model, workspace, and search backend
agent8088                    # start the interactive agent

The setup wizard stores API keys in ~/.agent8088/.env rather than config.txt. Start with a local Ollama model or select a hosted provider; the agent can switch models later with /model or /models.

full-auto is the default permission mode: the agent works without per-action prompts inside the workspace, with the always-on safety floor still enforced. Use --mode readonly to approve writes, network access, and shell commands one at a time.

The installer sets up the native sandbox automatically. If setup did not finish, run agent8088 --sandbox-setup to retry. On Windows, use your normal, non-admin terminal: the backend restricts f