agentsquid 0.1.0__tar.gz

agentsquid-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+__pycache__
+*.py[cod]
+*.egg-info/
+.venv
+dist/
+.env
+*.log
+squid.db
+.squid.pid
+tests/e2e/node_modules
+tests/e2e/playwright-report/
+tests/e2e/test-results/
+context/journals/
+context/topics/*
+!context/topics/default
+context/topics/default/*
+!context/topics/default/memory.md
+logs/
+.claude/
+benchmarks/claude_session_continuity/results
+config/squid.yaml

agentsquid-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Haebin Na
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentsquid-0.1.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: agentsquid
+Version: 0.1.0
+Summary: Locally running chat agent with access to Claude Code, Codex, and bash
+Project-URL: Homepage, https://agentsquid.ai
+Project-URL: Repository, https://github.com/agent-squid/squid
+Author: Haebin Na
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.9
+Requires-Dist: browser-cookie3>=0.19.0
+Requires-Dist: curl-cffi>=0.7.0
+Requires-Dist: fastapi>=0.111.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: uvicorn[standard]>=0.29.0
+Description-Content-Type: text/markdown
+
+# 🦑 AgentSquid
+```
+    🦑 AGENT
+    ██████╗ ██████╗ ██╗   ██╗██╗██████╗
+   ██╔════╝██╔═══██╗██║   ██║██║██╔══██╗
+   ╚█████╗ ██║   ██║██║   ██║██║██║  ██║
+    ╚═══██╗██║▄▄ ██║██║   ██║██║██║  ██║
+   ██████╔╝╚██████╔╝╚██████╔╝██║██████╔╝
+   ╚═════╝  ╚══▀▀═╝  ╚═════╝ ╚═╝╚═════╝
+```
+## Quick Start
+
+1. Install at least one supported CLI and check whether you can use it (/login):
+
+| Backend | CLI | Install |
+|---|---|---|
+| Claude Code | `claude` | `curl -fsSL https://claude.ai/install.sh \| bash` |
+| OpenAI Codex | `codex` | `curl -fsSL https://chatgpt.com/codex/install.sh \| sh` |
+| Cursor Agent | `cursor-agent` | `curl -fsS https://cursor.com/install \| bash` |
+| OpenCode | `opencode` | `curl -fsSL https://opencode.ai/install \| bash` |
+| Pi | `pi` | `curl -fsSL https://pi.dev/install.sh \| sh` |
+
+2. Install and run AgentSquid!
+
+```bash
+curl -fsSL https://agentsquid.ai/install.sh | sh
+agentsquid
+```
+
+3. Open in your browser:
+```text
+http://127.0.0.1:8000
+```
+
+Create agents in the UI. An agent is a named config:
+```text
+agent name (@agent) = harness (Claude Code) + provider (Claude) + model (claude-sonnet-5) + working directory (CLAUDE.md, etc.)
+```
+
+## The Squid Manifesto: EVERY. TOKEN. COUNTS!
+
+* COUNT every token, every prompt!
+* UNIFY your subscriptions, free tiers, and local models into one workplace.
+* SHARE context explicitly across models, topics, sessions; no waste!
+* CLEAR old context without fear; AgentSquid alerts you to clear and let you choose exactly what stays!
+* PARALLELIZE your prompts, no more waiting!
+
+## Your Local Coding Agents, Unified
+
+Agent-Squid is a **meta harness orchestrator** which lets you run Claude Code, OpenAI Codex, Cursor Agent, OpenCode, Pi **coding agents** with **multiple providers**, such as, Claude, GPT, Cursor, OpenCode, NVIDIA, DeepSeek, local LLMs via **one browser UI**. Your agents still run on your own machine, with your repo, shell tools, credentials, and native CLI sessions. Squid gives those sessions names, history, queues, controls, and phone/tablet access.
+
+Use it when your workflow has become a wall of unnamed terminal tabs or you need to use multiple coding agents; a couple of $20 agents alongside a free coding agent.
+
+```text
+#launch@claude write the release notes
+#launch@codex! review the diff for regressions
+#bug@cursor reproduce the auth failure
+#ops@opencode summarize the incident notes
+#research@pi compare the implementation options
+```
+NOTE: These topics are sticky. Once you are in the topic, no need to type it. :)
+
+## Why
+
+CLI agents are useful, but the workflow gets messy quickly:
+
+- You have ten Claude Code terminals open and cannot remember which one is doing what.
+- A terminal closes or the machine reboots, and reviving the right session becomes a hunt through resume pickers, session IDs, cwd-sensitive history, and shell scrollback.
+- Long-running sessions grow, drift, stall, and need compaction or reset but afraid to lose details.
+- There is no way to select responses as context for the next new session, so you have to tell it again.
+- Different agent CLIs have different commands, resume flags, slash commands, output formats, and UI assumptions.
+- Token usage is usually hidden in the flow instead of attached clearly to each prompt and response.
+- You want to do couch coding, but /remote doesn't cut it because not optimized for mobile.
+
+Squid turns those local agents into named, durable lanes you can control from a single chat thread with filter support.
+
+Topics and agents are not a rigid setup step. You can create a new `#topic` the moment you type it, switch agents with `@agent`, and clean up old workstreams when they are done. Squid treats tags as the UI for your agent work: lightweight enough to create dynamically, durable enough to recover later, and visible enough that you are not guessing which terminal was doing what.
+
+## What You Get
+
+- **Named agent lanes:** `#topic@agent` gives every workstream a durable identity.
+- **Dynamic tags:** create topics as you type, reuse sticky agents, filter by tag, and delete stale topics when the work is done.
+- **Native resumable sessions:** Squid tracks session handles while the CLI owns its real context.
+- **Parallel work:** different topics and agents run independently.
+- **Adhoc (Goldfish) mode:** `#topic@agent!` runs a fresh one-off job immediately without polluting the main session. You can add the adhoc output to session context easily. (merging context)
+- **Session vs. limited-context comparison:** compare a session lane against an adhoc prompt that includes only the last N exchanges.
+- **Live progress bubble:** watch queued state, tool/status output, and partial response progress while the CLI is working.
+- **Auto-compaction hint:** alerts you to /clear the session if it's stale or too many turns.
+- **Context pin:** pin a useful answer and inject it into another session or adhoc turn.
+- **Context bookmark:** bookmark a useful answer and use it later for context.
+- **Process controls:** stop one process from the UI, stop by command, stop a topic, drain queues, clear sessions, and compact/reset context.
+- **History and filtering:** scan past work by topic, agent, or adhoc lane.
+- **Analytics:** review usage by time, topic, or agent, plus live process state.
+- **Per-prompt usage:** every completed prompt can show input, output, cache, reasoning, cost, duration, and quota signals when the backend exposes them.
+- **Phone/tablet access:** lie on the couch while your local machine keeps coding.
+
+## Basic Usage
+
+| Syntax | Meaning |
+|---|---|
+| `#topic@agent message` | Continue that topic/agent session |
+| `#topic@agent! message` | Run a parallel adhoc turn with no session history |
+| `#topic@agent!3 message` | Run adhoc with only the last 3 exchanges (normal, searched, filtered) as context |
+| `/stop` | Stop the current process scope |
+| `/stopall` | Stop and drain the current topic |
+| `/clear` | Create new session |
+| `/f`, `/filter` | Filter history to the current topic/agent lane |
+| `/s`, `/search` | Search history to the current topic/agent lane |
+| `/remote` | Show QR code for mobile/tablet access via Tailscale |
+
+Session turns are queued per `#topic@agent` for the tasks with order matters. Adhoc `!` turns are independent and run immediately.
+
+This makes comparison easy. Ask the session with `#topic@agent`, then ask a limited-context version with `#topic@agent!3`, `#topic@agent!1`, or `#topic@agent!`. You can see whether the long session is helping, whether stale context is hurting, and how much token usage each path costs.
+
+Tags are created dynamically. If you send `#release@claude ...`, Squid creates or updates the `release` topic and remembers `claude` as its sticky agent. Later, `#release ...` continues that lane without retyping the agent. Topic autocomplete lets you browse existing tags, and old topics can be hidden or deleted when they are no longer useful.
+
+While an agent is running, Squid shows progress in a thought bubble instead of leaving you staring at a frozen terminal. You can see queue position, status output, tool activity, and streamed partial content. If the job is going in the wrong direction, stop it from the bubble’s UI control or type `/stop`, `/stopall`, or `deq` just like you would use CLI control commands, but with clearer scope and feedback.
+
+After completion, the response carries usage metadata. Instead of guessing what a turn cost, you can inspect tokens, cache reads/writes, reasoning tokens where available, duration, cost, and quota deltas. The analytics view rolls this up by time, topic, and agent so you can see which lanes are expensive and which models are doing the most work.
+
+## Couch Coding With Tailscale
+
+Squid is most useful when your local machine can keep working while you are away from the desk.
+
+Tailscale is a good fit for this. Its Personal plan is free for non-commercial personal use, and it creates a private WireGuard-based network across your own devices. Your phone, tablet, laptop, Mac mini, and workstation can talk inside the tailnet without opening a public port.
+
+Squid always binds to `127.0.0.1`, it never exposes itself directly on the network. Starting squid automatically configures Tailscale's HTTPS proxy if Tailscale is installed:
+
+```bash
+agentsquid   # configures tailscale serve automatically
+```
+
+Type `/remote` in the chat to get a QR code with the full HTTPS URL and your
+token already included — point your phone camera at it to open squid in one tap:
+
+```text
+https://<machine-name>.<tailnet>.ts.net/?token=<your-token>
+```
+
+The full domain is required — the short hostname alone (`https://<machine-name>/`)
+won't work because Tailscale's TLS cert is scoped to `*.ts.net` and browsers
+enforce an exact match.
+
+## How Squid Is Different
+
+Squid is not another general AI chat app. Open WebUI and LibreChat are broad self-hosted chat platforms for many providers, RAG, plugins, users, memory, and web search.
+
+Squid is narrower: it controls real local coding-agent CLIs and preserves their session behavior.
+
+Most chat UIs send messages to a model API and render text back. Even when they support tools or agents, the chat app is usually the runtime. Squid is different: the runtime is still the local CLI agent. Claude Code, Codex, Cursor Agent, OpenCode, and Pi are the process doing the work on your machine. Squid is the interactive control layer around those processes.
+
+That difference matters:
+
+- **Real CLI sessions, not copied chat history:** Squid uses the agent’s native session instead of pretending to be the agent with a replayed transcript.
+- **Working-directory awareness:** sessions are tied to the cwd where the CLI actually runs, which matters for local project context and resume behavior. You can change it to your local home to inherit all the settings. (note: this will burn a bit more tokens for additional context)
+- **Process ownership:** Squid can show live processes, kill the exact running job, drain queued jobs, and recover after disconnects.
+- **Topic and agent lanes:** `#topic@agent` is closer to a named terminal workspace than a chat room. You can easily filter it to look like a chat room.
+- **Progress while work happens:** the thought bubble surfaces status, queued state, tool activity, and partial output before the final answer lands.
+- **UI plus command control:** click to stop a specific run, or type commands like `/stop`, `/stopall`, `/clear`, `/compact`, and `/filter`.
+- **Analytics attached to real work:** token usage is tied to each prompt and can be rolled up by topic, agent, or time.
+- **Built-in context experiments:** compare a native resumed session against an adhoc turn with only selected recent context.
+- **Local machine as the backend:** your Mac mini or workstation stays the execution environment, so the agent has the same filesystem, shell, credentials, and installed tools it would have in a terminal.
+
+| Category | Examples | Squid's difference |
+|---|---|---|
+| Self-hosted AI chat | Open WebUI, LibreChat | Squid runs local CLI coding agents instead of replacing them with a provider chat UI. |
+| Single-agent CLIs | Claude Code, Codex CLI, Cursor Agent, OpenCode, Pi | Squid gives them shared browser/mobile UI, topics, queues, history, controls, and analytics. |
+| IDE agents | Cursor, Cline, VS Code Copilot | Squid is editor-agnostic and works even when the IDE is not open. |
+| Terminal pair programmers | Aider, OpenCode | Squid is an orchestration layer, not a coding engine. |
+
+Use the agent directly when one terminal is enough. Use Squid when you want several local agents, named sessions, mobile access, process control, recoverable long-running work, and analytics that explain what each lane is costing you.
+
+## Architecture
+
+```text
+Browser / phone / tablet
+        |
+        | HTTP + SSE
+        v
+FastAPI Squid server
+        |
+        +-- SQLite history, stats, topics, session handles
+        |
+        +-- TopicDispatcher
+              |
+              +-- FIFO worker per #topic@agent session lane
+              +-- ephemeral worker per adhoc ! turn
+        |
+        +-- local CLI subprocesses
+              claude / codex / cursor-agent / opencode / pi
+```
+
+The CLI owns the real conversation context. Squid stores history, stats, topics, active session IDs, cwd locks, and UI state needed to make the workflow manageable. Session turns use native resume. Adhoc turns build an explicit limited-context prompt, which makes the two modes easy to compare.
+
+## Good Fit
+
+Squid is a good fit if:
+
+- You run multiple coding-agent terminals at once.
+- You want to recover and operate sessions by name.
+- You use a local Mac mini, workstation, or always-on machine for agent work.
+- You want phone/tablet control without moving execution to the cloud.
+- You compare or combine several agent CLIs.
+- You want to compare full-session context against limited-history prompts.
+- You care about token usage, cost, cache behavior, and per-topic or per-agent analytics.
+
+It may be overkill if:
+
+- You only ever use one agent in one terminal.
+- You want a hosted team chat product.
+- You want Squid to be the coding agent itself.

agentsquid-0.1.0/README.md

@@ -0,0 +1,211 @@
+# 🦑 AgentSquid
+```
+    🦑 AGENT
+    ██████╗ ██████╗ ██╗   ██╗██╗██████╗
+   ██╔════╝██╔═══██╗██║   ██║██║██╔══██╗
+   ╚█████╗ ██║   ██║██║   ██║██║██║  ██║
+    ╚═══██╗██║▄▄ ██║██║   ██║██║██║  ██║
+   ██████╔╝╚██████╔╝╚██████╔╝██║██████╔╝
+   ╚═════╝  ╚══▀▀═╝  ╚═════╝ ╚═╝╚═════╝
+```
+## Quick Start
+
+1. Install at least one supported CLI and check whether you can use it (/login):
+
+| Backend | CLI | Install |
+|---|---|---|
+| Claude Code | `claude` | `curl -fsSL https://claude.ai/install.sh \| bash` |
+| OpenAI Codex | `codex` | `curl -fsSL https://chatgpt.com/codex/install.sh \| sh` |
+| Cursor Agent | `cursor-agent` | `curl -fsS https://cursor.com/install \| bash` |
+| OpenCode | `opencode` | `curl -fsSL https://opencode.ai/install \| bash` |
+| Pi | `pi` | `curl -fsSL https://pi.dev/install.sh \| sh` |
+
+2. Install and run AgentSquid!
+
+```bash
+curl -fsSL https://agentsquid.ai/install.sh | sh
+agentsquid
+```
+
+3. Open in your browser:
+```text
+http://127.0.0.1:8000
+```
+
+Create agents in the UI. An agent is a named config:
+```text
+agent name (@agent) = harness (Claude Code) + provider (Claude) + model (claude-sonnet-5) + working directory (CLAUDE.md, etc.)
+```
+
+## The Squid Manifesto: EVERY. TOKEN. COUNTS!
+
+* COUNT every token, every prompt!
+* UNIFY your subscriptions, free tiers, and local models into one workplace.
+* SHARE context explicitly across models, topics, sessions; no waste!
+* CLEAR old context without fear; AgentSquid alerts you to clear and let you choose exactly what stays!
+* PARALLELIZE your prompts, no more waiting!
+
+## Your Local Coding Agents, Unified
+
+Agent-Squid is a **meta harness orchestrator** which lets you run Claude Code, OpenAI Codex, Cursor Agent, OpenCode, Pi **coding agents** with **multiple providers**, such as, Claude, GPT, Cursor, OpenCode, NVIDIA, DeepSeek, local LLMs via **one browser UI**. Your agents still run on your own machine, with your repo, shell tools, credentials, and native CLI sessions. Squid gives those sessions names, history, queues, controls, and phone/tablet access.
+
+Use it when your workflow has become a wall of unnamed terminal tabs or you need to use multiple coding agents; a couple of $20 agents alongside a free coding agent.
+
+```text
+#launch@claude write the release notes
+#launch@codex! review the diff for regressions
+#bug@cursor reproduce the auth failure
+#ops@opencode summarize the incident notes
+#research@pi compare the implementation options
+```
+NOTE: These topics are sticky. Once you are in the topic, no need to type it. :)
+
+## Why
+
+CLI agents are useful, but the workflow gets messy quickly:
+
+- You have ten Claude Code terminals open and cannot remember which one is doing what.
+- A terminal closes or the machine reboots, and reviving the right session becomes a hunt through resume pickers, session IDs, cwd-sensitive history, and shell scrollback.
+- Long-running sessions grow, drift, stall, and need compaction or reset but afraid to lose details.
+- There is no way to select responses as context for the next new session, so you have to tell it again.
+- Different agent CLIs have different commands, resume flags, slash commands, output formats, and UI assumptions.
+- Token usage is usually hidden in the flow instead of attached clearly to each prompt and response.
+- You want to do couch coding, but /remote doesn't cut it because not optimized for mobile.
+
+Squid turns those local agents into named, durable lanes you can control from a single chat thread with filter support.
+
+Topics and agents are not a rigid setup step. You can create a new `#topic` the moment you type it, switch agents with `@agent`, and clean up old workstreams when they are done. Squid treats tags as the UI for your agent work: lightweight enough to create dynamically, durable enough to recover later, and visible enough that you are not guessing which terminal was doing what.
+
+## What You Get
+
+- **Named agent lanes:** `#topic@agent` gives every workstream a durable identity.
+- **Dynamic tags:** create topics as you type, reuse sticky agents, filter by tag, and delete stale topics when the work is done.
+- **Native resumable sessions:** Squid tracks session handles while the CLI owns its real context.
+- **Parallel work:** different topics and agents run independently.
+- **Adhoc (Goldfish) mode:** `#topic@agent!` runs a fresh one-off job immediately without polluting the main session. You can add the adhoc output to session context easily. (merging context)
+- **Session vs. limited-context comparison:** compare a session lane against an adhoc prompt that includes only the last N exchanges.
+- **Live progress bubble:** watch queued state, tool/status output, and partial response progress while the CLI is working.
+- **Auto-compaction hint:** alerts you to /clear the session if it's stale or too many turns.
+- **Context pin:** pin a useful answer and inject it into another session or adhoc turn.
+- **Context bookmark:** bookmark a useful answer and use it later for context.
+- **Process controls:** stop one process from the UI, stop by command, stop a topic, drain queues, clear sessions, and compact/reset context.
+- **History and filtering:** scan past work by topic, agent, or adhoc lane.
+- **Analytics:** review usage by time, topic, or agent, plus live process state.
+- **Per-prompt usage:** every completed prompt can show input, output, cache, reasoning, cost, duration, and quota signals when the backend exposes them.
+- **Phone/tablet access:** lie on the couch while your local machine keeps coding.
+
+## Basic Usage
+
+| Syntax | Meaning |
+|---|---|
+| `#topic@agent message` | Continue that topic/agent session |
+| `#topic@agent! message` | Run a parallel adhoc turn with no session history |
+| `#topic@agent!3 message` | Run adhoc with only the last 3 exchanges (normal, searched, filtered) as context |
+| `/stop` | Stop the current process scope |
+| `/stopall` | Stop and drain the current topic |
+| `/clear` | Create new session |
+| `/f`, `/filter` | Filter history to the current topic/agent lane |
+| `/s`, `/search` | Search history to the current topic/agent lane |
+| `/remote` | Show QR code for mobile/tablet access via Tailscale |
+
+Session turns are queued per `#topic@agent` for the tasks with order matters. Adhoc `!` turns are independent and run immediately.
+
+This makes comparison easy. Ask the session with `#topic@agent`, then ask a limited-context version with `#topic@agent!3`, `#topic@agent!1`, or `#topic@agent!`. You can see whether the long session is helping, whether stale context is hurting, and how much token usage each path costs.
+
+Tags are created dynamically. If you send `#release@claude ...`, Squid creates or updates the `release` topic and remembers `claude` as its sticky agent. Later, `#release ...` continues that lane without retyping the agent. Topic autocomplete lets you browse existing tags, and old topics can be hidden or deleted when they are no longer useful.
+
+While an agent is running, Squid shows progress in a thought bubble instead of leaving you staring at a frozen terminal. You can see queue position, status output, tool activity, and streamed partial content. If the job is going in the wrong direction, stop it from the bubble’s UI control or type `/stop`, `/stopall`, or `deq` just like you would use CLI control commands, but with clearer scope and feedback.
+
+After completion, the response carries usage metadata. Instead of guessing what a turn cost, you can inspect tokens, cache reads/writes, reasoning tokens where available, duration, cost, and quota deltas. The analytics view rolls this up by time, topic, and agent so you can see which lanes are expensive and which models are doing the most work.
+
+## Couch Coding With Tailscale
+
+Squid is most useful when your local machine can keep working while you are away from the desk.
+
+Tailscale is a good fit for this. Its Personal plan is free for non-commercial personal use, and it creates a private WireGuard-based network across your own devices. Your phone, tablet, laptop, Mac mini, and workstation can talk inside the tailnet without opening a public port.
+
+Squid always binds to `127.0.0.1`, it never exposes itself directly on the network. Starting squid automatically configures Tailscale's HTTPS proxy if Tailscale is installed:
+
+```bash
+agentsquid   # configures tailscale serve automatically
+```
+
+Type `/remote` in the chat to get a QR code with the full HTTPS URL and your
+token already included — point your phone camera at it to open squid in one tap:
+
+```text
+https://<machine-name>.<tailnet>.ts.net/?token=<your-token>
+```
+
+The full domain is required — the short hostname alone (`https://<machine-name>/`)
+won't work because Tailscale's TLS cert is scoped to `*.ts.net` and browsers
+enforce an exact match.
+
+## How Squid Is Different
+
+Squid is not another general AI chat app. Open WebUI and LibreChat are broad self-hosted chat platforms for many providers, RAG, plugins, users, memory, and web search.
+
+Squid is narrower: it controls real local coding-agent CLIs and preserves their session behavior.
+
+Most chat UIs send messages to a model API and render text back. Even when they support tools or agents, the chat app is usually the runtime. Squid is different: the runtime is still the local CLI agent. Claude Code, Codex, Cursor Agent, OpenCode, and Pi are the process doing the work on your machine. Squid is the interactive control layer around those processes.
+
+That difference matters:
+
+- **Real CLI sessions, not copied chat history:** Squid uses the agent’s native session instead of pretending to be the agent with a replayed transcript.
+- **Working-directory awareness:** sessions are tied to the cwd where the CLI actually runs, which matters for local project context and resume behavior. You can change it to your local home to inherit all the settings. (note: this will burn a bit more tokens for additional context)
+- **Process ownership:** Squid can show live processes, kill the exact running job, drain queued jobs, and recover after disconnects.
+- **Topic and agent lanes:** `#topic@agent` is closer to a named terminal workspace than a chat room. You can easily filter it to look like a chat room.
+- **Progress while work happens:** the thought bubble surfaces status, queued state, tool activity, and partial output before the final answer lands.
+- **UI plus command control:** click to stop a specific run, or type commands like `/stop`, `/stopall`, `/clear`, `/compact`, and `/filter`.
+- **Analytics attached to real work:** token usage is tied to each prompt and can be rolled up by topic, agent, or time.
+- **Built-in context experiments:** compare a native resumed session against an adhoc turn with only selected recent context.
+- **Local machine as the backend:** your Mac mini or workstation stays the execution environment, so the agent has the same filesystem, shell, credentials, and installed tools it would have in a terminal.
+
+| Category | Examples | Squid's difference |
+|---|---|---|
+| Self-hosted AI chat | Open WebUI, LibreChat | Squid runs local CLI coding agents instead of replacing them with a provider chat UI. |
+| Single-agent CLIs | Claude Code, Codex CLI, Cursor Agent, OpenCode, Pi | Squid gives them shared browser/mobile UI, topics, queues, history, controls, and analytics. |
+| IDE agents | Cursor, Cline, VS Code Copilot | Squid is editor-agnostic and works even when the IDE is not open. |
+| Terminal pair programmers | Aider, OpenCode | Squid is an orchestration layer, not a coding engine. |
+
+Use the agent directly when one terminal is enough. Use Squid when you want several local agents, named sessions, mobile access, process control, recoverable long-running work, and analytics that explain what each lane is costing you.
+
+## Architecture
+
+```text
+Browser / phone / tablet
+        |
+        | HTTP + SSE
+        v
+FastAPI Squid server
+        |
+        +-- SQLite history, stats, topics, session handles
+        |
+        +-- TopicDispatcher
+              |
+              +-- FIFO worker per #topic@agent session lane
+              +-- ephemeral worker per adhoc ! turn
+        |
+        +-- local CLI subprocesses
+              claude / codex / cursor-agent / opencode / pi
+```
+
+The CLI owns the real conversation context. Squid stores history, stats, topics, active session IDs, cwd locks, and UI state needed to make the workflow manageable. Session turns use native resume. Adhoc turns build an explicit limited-context prompt, which makes the two modes easy to compare.
+
+## Good Fit
+
+Squid is a good fit if:
+
+- You run multiple coding-agent terminals at once.
+- You want to recover and operate sessions by name.
+- You use a local Mac mini, workstation, or always-on machine for agent work.
+- You want phone/tablet control without moving execution to the cloud.
+- You compare or combine several agent CLIs.
+- You want to compare full-session context against limited-history prompts.
+- You care about token usage, cost, cache behavior, and per-topic or per-agent analytics.
+
+It may be overkill if:
+
+- You only ever use one agent in one terminal.
+- You want a hosted team chat product.
+- You want Squid to be the coding agent itself.

agentsquid-0.1.0/activate.sh

@@ -0,0 +1 @@
+source .venv/bin/activate

agentsquid-0.1.0/agent/config.py

@@ -0,0 +1,137 @@
+import getpass
+import hashlib
+import os
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Optional
+import yaml
+
+_USER_CONFIG = Path.home() / ".squid" / "squid.yaml"
+_EXAMPLE_CONFIG = Path(__file__).parent.parent / "config" / "squid.yaml.example"
+
+
+def _bootstrap_config() -> None:
+    """Create ~/.squid/squid.yaml from the bundled example on first run.
+
+    bin/install.sh and bin/start.sh do this same substitution for a source
+    checkout, but a pip/pipx install never runs either script, so this has
+    to also happen here — otherwise a fresh pipx install has no config file
+    and _load_config() below crashes on the very first launch.
+    """
+    if _USER_CONFIG.exists() or not _EXAMPLE_CONFIG.exists():
+        return
+    _USER_CONFIG.parent.mkdir(parents=True, exist_ok=True)
+    text = _EXAMPLE_CONFIG.read_text(encoding="utf-8")
+    text = text.replace("/tmp/squid", f"/tmp/{getpass.getuser()}/squid")
+    _USER_CONFIG.write_text(text, encoding="utf-8")
+
+
+def _load_config() -> dict:
+    _bootstrap_config()
+    return yaml.safe_load(_USER_CONFIG.read_text())
+
+
+def config_text() -> str:
+    return _USER_CONFIG.read_text(encoding="utf-8")
+
+
+def config_revision(content: Optional[str] = None) -> str:
+    raw = config_text() if content is None else content
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()[:16]
+
+
+def write_config_text(content: str, expected_revision: Optional[str] = None) -> str:
+    """Atomically replace squid.yaml, retaining the previous version as .bak."""
+    if expected_revision is not None and config_revision() != expected_revision:
+        raise RuntimeError("configuration changed since it was loaded")
+
+    mode = _USER_CONFIG.stat().st_mode & 0o777
+    backup = _USER_CONFIG.with_suffix(_USER_CONFIG.suffix + ".bak")
+    shutil.copy2(_USER_CONFIG, backup)
+    fd, tmp_name = tempfile.mkstemp(prefix=".squid.yaml.", dir=_USER_CONFIG.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(content)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.chmod(tmp_name, mode)
+        os.replace(tmp_name, _USER_CONFIG)
+    finally:
+        if os.path.exists(tmp_name):
+            os.unlink(tmp_name)
+    return config_revision(content)
+
+_cfg = _load_config()
+
+# CLI executable names — override via env if installed elsewhere
+CLAUDE_CLI    = "claude"
+CODEX_CLI     = "codex"
+CURSOR_CLI    = "cursor-agent"
+OPENCODE_CLI  = "opencode"
+PI_CLI        = "pi"
+
+# Experimental runners exist for these CLIs but they are not configurable harnesses.
+COPILOT_CLI  = "copilot"
+AGY_CLI      = "agy"
+
+# Squid Echo: a no-op harness (agent/runners.py's run_echo) that echoes the
+# prompt straight back with no subprocess and no network call — for fast,
+# free previews of how a Squid Flow route actually dispatches/executes
+# (joins, round-trips, broadcasts, ...) without a real coding-agent CLI in
+# the loop. Opt-in only (absent/false by default), so it never shows up for
+# a user who hasn't asked for it; harnesses.py and providers.py both gate on
+# this flag. Settable either way — `test_harness_enabled: true` in
+# squid.yaml (picked up on every restart, since /restart re-execs and
+# re-reads the file) or the SQUID_TEST_HARNESS env var (for CI/one-offs).
+TEST_HARNESS_ENABLED: bool = bool(_cfg.get("test_harness_enabled")) or bool(os.environ.get("SQUID_TEST_HARNESS"))
+
+# How long to wait for a CLI to produce its first byte before giving up
+FIRST_BYTE_TIMEOUT: int = _cfg["agent"]["first_byte_timeout"]
+
+# Hard cap on total response time per request
+RESPONSE_TIMEOUT: int = _cfg["agent"]["response_timeout"]
+
+def find_cli(name: str) -> Optional[str]:
+    return shutil.which(name)
+
+CLAUDE_PATH    = find_cli(CLAUDE_CLI)
+CODEX_PATH     = find_cli(CODEX_CLI)
+COPILOT_PATH   = find_cli(COPILOT_CLI)
+CURSOR_PATH    = find_cli(CURSOR_CLI)
+OPENCODE_PATH  = find_cli(OPENCODE_CLI)
+PI_PATH        = find_cli(PI_CLI)
+AGY_PATH       = find_cli(AGY_CLI)
+
+# OpenCode free provider — no API key required
+OPENCODE_DEFAULT_MODEL = "opencode/deepseek-v4-flash-free"
+
+# Per-user tmp dir for context sync — avoids cross-user permission conflicts
+SQUID_HOME = f"/tmp/{os.getlogin()}/squid"
+
+# Per-turn Git worktree isolation (see ADR-0025). On by default; set
+# `worktree.enabled: false` in squid.yaml to use direct working-tree writes.
+_worktree_cfg = _cfg.get("worktree", {})
+WORKTREE_ISOLATION_ENABLED: bool = bool(_worktree_cfg.get("enabled", True))
+WORKTREE_TRACK_DIRTY_CHANGES: bool = bool(_worktree_cfg.get("track_dirty_changes", False))
+
+# Dependency/cache directory names to symlink from a code root into each fresh
+# per-turn worktree. auto_link_ignored_dirs only links ignored dirs whose
+# basename appears in this allowlist.
+WORKTREE_AUTO_LINK_IGNORED_DIRS: bool = bool(_worktree_cfg.get("auto_link_ignored_dirs", True))
+DEPENDENCY_DIRS: list[str] = _worktree_cfg.get("dependency_dirs", [
+    "node_modules", ".venv", "venv", "env", ".tox", "__pypackages__",
+    "vendor", "target", ".bundle", "Pods", ".cargo", ".stack-work", "elm-stuff",
+])
+
+# Proxy environment to inject into every CLI subprocess, or None if disabled.
+_proxy_cfg = _cfg.get("proxy", {})
+PROXY_ENV: Optional[dict] = None
+if _proxy_cfg.get("enabled"):
+    _proxy_url = _proxy_cfg.get("url", "http://127.0.0.1:8080")
+    _cert = os.path.expanduser(_proxy_cfg.get("ssl_cert_file", "~/.mitmproxy/mitmproxy-ca-cert.pem"))
+    PROXY_ENV = {
+        "HTTP_PROXY": _proxy_url,
+        "HTTPS_PROXY": _proxy_url,
+        "SSL_CERT_FILE": _cert,
+    }