- 
+ 
-brightgreen){kind=icon}
- An ambient, persistent desktop companion with perception and memory.
+ An ambient, persistent desktop AI companion with perception and memory for your daily work and engineering workflows.
Observes your workspace quietly. Synthesizes context deeply. Acts decisively. Governed by you.
-
+ 
-brightgreen){kind=icon}
@@ -23,39 +23,52 @@
## ð¡ What is Squid?
-Most AI tools today are **passive chat boxes**: you hit an error, copy-paste terminal outputs, re-explain your project architecture for the tenth time, and coax the model into understanding what you were doing.
+Most AI tools today are **passive chat boxes**:
+Whether you are analyzing business data, reconciling deliverables across software, drafting documents, or running automation scripts and engineering pipelines, hitting a roadblock forces you to break your flow â switching windows, taking screenshots, copy-pasting error traces or project briefs, and re-explaining for the tenth time what you were doing.
**Squid flips this paradigm.**
-Squid is an **ambient, long-lived desktop AI companion** built on the [Pi agent runtime](https://github.com/earendil-works/pi-ai). Instead of waiting for you to copy-paste context, Squid quietly runs in your background and perceives your workstation activity in real time:
-- The project files you save in your editor
-- The commands you run in your shell and their exit codes
-- The active window, focused UI control, and selected text on your screen
-- The API reference or GitHub issue you are reading in your browser
+Squid is an **ambient, long-lived desktop personal AI companion** built on the [Pi agent runtime](https://github.com/earendil-works/pi-ai). It is **not merely a coding agent designed for writing code**, but a proactive companion built for **engineering tasks, digital workflows, and everyday personal productivity**. Running quietly in the background with minimal resource overhead, Squid continuously perceives your desktop activity:
+- **Work Documents & Project Assets**: Documents, spreadsheets, presentations, design assets, and configuration files you create or update;
+- **Task Scripts & Automation Pipelines**: Data batch processing, Python scripts, backup jobs, and shell commands running in your background terminals;
+- **Desktop Application & Interaction Context**: Active application windows, focused UI controls, and text you are reading or selecting on your screen;
+- **Web Research & Business Portals**: Project management boards (Jira, Linear, Notion), technical specifications, industry references, and browser tabs you explore.
-Squid continuously distills these observations into a coherent **episodic world state**. When things go wrong or when assistance is needed, Squid already knows the full story â stepping in with timely insights and actions, while remaining strictly under your control.
+Squid continuously distills these observations into a coherent **episodic world state**. When workflows hit an error, information needs cross-referencing between applications, or proactive execution is warranted, Squid already knows the full story â stepping in with timely insights, root-cause diagnosis, or workflow assistance, while remaining strictly governed by your explicit control.
---
## ð A Day with Squid: Real-World Scenarios
-### 1. â¡ Terminal Errors? No More Copy-Pasting Stacks
-You run a test suite or deployment command in your terminal (`cargo test`, `pytest`, `npm run build`) and hit a compiler error or assertion failure.
-> **Without Squid**: You select text in the terminal, switch windows to a browser or chat window, paste the trace, and type *"why did this fail?"*.
+### 1. ð Cross-App Workflow Synthesis: From Web Briefs to Local Documents
+You examine customer requirements, project tickets, or an industry whitepaper in your browser, then switch to a local spreadsheet, proposal draft, or configuration document to organize deliverables.
+> **Without Squid**: You repeatedly switch between browser tabs and desktop apps, copy-pasting requirements into an AI chat window and prompting *"please summarize this against my open file"*.
>
-> **With Squid**: Squid hooks terminal completions. It already knows the command, the failure exit code, and the files you edited right before running it. It synthesizes the root cause immediately without you copying a single line.
+> **With Squid**: Squid connects the dots between the reference page you just browsed and the local file you are editing. When you request a summary, consistency check, or proposal draft, it leverages the full context automatically without manual copying.
-### 2. ð Cross-Window Context: It Connects the Dots
-You browse an open-source documentation site in Chrome, then switch back to VS Code to implement a function.
-> **With Squid**: Squid notices the active browser tab URL and the code you are saving. When asked for suggestions or generating completions, it pulls context from the exact documentation page you were just looking at.
+### 2. â¡ Engineering & Script Failures: Instant Root-Cause Without Copy-Pasting
+You run a data-cleaning pipeline, automated report generator, file conversion script, or deployment CLI command in the background, and it fails with an unexpected exit code or stack trace.
+> **Without Squid**: You scroll back through noisy terminal output, find the error lines, paste them into a chat assistant, and explain what inputs or files you modified prior to running it.
+>
+> **With Squid**: Squid hooks command completions in real time. It already knows the failing command, the non-zero exit code, and the specific files or data you touched right before running it. It pinpoints the root cause immediately and can propose an automated fix or retry plan.
+
+### 3. ð§ Interruption Recovery: Seamless Multitasking Context Memory
+In the middle of cross-referencing complex data across multiple spreadsheets, an urgent phone call or impromptu meeting pulls you away. Thirty minutes later you sit back down at your desk: *"Where was I?"*
+> **Without Squid**: You search through a dozen open windows, browser tabs, and folders trying to reconstruct your train of thought.
+>
+> **With Squid**: Squid maintains structured episodic memory. A quick glance at the panel gives you a concise recap of your immediate context prior to the interruption â e.g. *"You were comparing metrics between Sheet A and the Q3 Portal, working on section 2 of the summary document"*.
-### 3. ð Zero Distraction & Smart Notifications
-Nobody likes an AI that interrupts every three seconds like an over-eager assistant.
-> **With Squid**: Squid operates under an explicit *permission to do nothing* philosophy. It only triggers a desktop toast notification (Linux `notify-send`, Windows `Shell_NotifyIcon`, macOS `osascript`) **when it has actually executed a real action or file change**. If it is merely reading, thinking, or deciding no action is required, it stays 100% quiet.
+### 4. ðïž Proactive Personal Assist: File Triage & Repetitive Task Relief
+You frequently download batches of invoices, research reports, or data exports into your Downloads folder, requiring recurring cleanup and organization.
+> **Without Squid**: You periodically spend 20 minutes manually creating folders, renaming files, and dragging them into archives.
+>
+> **With Squid**: Squid observes incoming file patterns in your watched workspace. It can proactively suggest clean naming conventions and folder structures, and upon your confirmation, organize or process them automatically.
-### 4. ð¡ïž Automatic Privacy Shields
-You open your password manager or banking portal to grab an API token or verify a billing detail.
-> **With Squid**: Squid detects the foreground application (`1Password`, `Bitwarden`, `KeePassXC`, or custom exclusions via `SQUID_EXCLUDE`). Screen and window capture immediately suspend until you switch back. Secrets, passwords, and tokens are scrubbed at the ingress before ever touching the database.
+### 5. ð¡ïž Absolute Discretion & Automatic Privacy Shields
+Nobody wants an overeager chatbot interrupting their focus every three seconds.
+> **With Squid**:
+> - **Permission to Do Nothing**: Squid follows an explicit zero-distraction philosophy. It triggers a desktop notification (Linux `notify-send`, Windows `Shell_NotifyIcon`, macOS `osascript`) **only when it has executed a concrete action or file change**. If it is merely observing, reading, or deciding no intervention is needed, it remains 100% silent.
+> - **Automatic Privacy Shields**: The moment you switch to a password manager (`1Password`, `Bitwarden`, `KeePassXC`), online banking portal, or personal chat, screen and window capture immediately suspend. Secrets, tokens, and credentials are scrubbed at the ingress before reaching storage.
---
@@ -68,13 +81,13 @@ Get started in under 60 seconds with no compilers or complex dependencies requir
1. Download the latest release zip for your OS from [GitHub Releases](https://github.com/salmonloop/squid/releases):
- **Linux**: `squid-x86_64-unknown-linux-gnu.zip`
- **Windows**: `squid-x86_64-pc-windows-msvc.zip`
-2. Extract the archive. You will see two companion binaries:
- - `squid-ui`: The high-performance desktop panel (double-click to open).
+2. Extract the archive. You will find two companion binaries:
+ - `squid-ui`: The native desktop control panel (double-click to open).
- `squid`: The background sensory engine (supervised automatically by `squid-ui`).
3. Launch `squid-ui`:
- - It will open the sleek Fluent desktop panel and dock an icon in your system tray.
- - On first launch, navigate to **SETTINGS** to connect your favorite LLM provider:
- - **Cloud Providers**: OpenAI, Anthropic, DeepSeek, OpenRouter, etc.
+ - It opens the native Fluent desktop panel and docks an icon in your system tray.
+ - On first launch, navigate to **SETTINGS** to connect your preferred LLM provider:
+ - **Cloud Providers**: OpenAI, Anthropic Claude, DeepSeek, OpenRouter, etc.
- **Local & Private Models**: [Ollama](https://ollama.ai/), vLLM, LM Studio, or any OpenAI-compatible `/v1` endpoint.
---
@@ -98,7 +111,7 @@ cargo build --release --manifest-path ui/Cargo.toml
bun run start
```
-`bun run start` runs `src/squid-app.ts`: it defaults your home directory as the watch root, sets up the platform domain socket or Windows named pipe, launches the release panel binary, and connects the ambient sensory loop.
+`bun run start` executes `src/squid-app.ts`: it sets your home directory as the watch root, configures the platform domain socket or Windows named pipe, launches the release panel binary, and connects the ambient sensory loop.
---
@@ -110,12 +123,13 @@ Squid delivers a native desktop UI built in **Rust with Slint 1.17** that is lig
âââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ
â ðŠ SQUID [_] [â¡] [â] â
âââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ€
-â STATUS: Active · Watching /home/user/projects â
+â STATUS: Active · Watching /home/alex/workspace â
â Agent: Idle (Observed 14 events across 2 episodes) â
âââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ€
â [ACTIVITY EVIDENCE] â
-â ⢠VS Code: saved src/api-client.ts (2m ago) â
-â ⢠Terminal: `bun test` exited with code 0 (1m ago) â
+â ⢠Browser: Reviewing "Q3 Operations & Architecture Plan" â
+â ⢠Document: Updated project-roadmap.xlsx (1m ago) â
+â ⢠Terminal: Script `sync-data.py` finished with code 0 â
â â
â [TRIGGER LEDGER] â
â Triggered: 3 | Duplicate: 8 | Excluded: 1 | Coalesced: 4â
@@ -142,7 +156,7 @@ Squid can be configured via the **SETTINGS** tab in the desktop UI, through JSON
### General & Runtime
| Environment Variable | Config Key | Default | Description |
|---|---|---|---|
-| `SQUID_WATCH_ROOT` | `watchRoot` | `$HOME` | Directory watched by the filesystem sensor. |
+| `SQUID_WATCH_ROOT` | `watchRoot` | `$HOME` | Directory watched by the filesystem sensor (workspace, documents, or project root). |
| `SQUID_PANEL_SOCKET` | `panelEndpoint` | Auto | IPC endpoint (`/tmp/squid-panel.sock` or `\\.\pipe\squid-panel`). |
| `SQUID_NOTIFY` | `notify` | `desktop` | Notification mode (`desktop` or `off`). Only alerts when the agent acts. |
@@ -161,29 +175,29 @@ Squid can be configured via the **SETTINGS** tab in the desktop UI, through JSON
|---|---|---|---|
| `SQUID_SCREEN_READER` | `screenReaderBackend` | Host native | Screen reader backend: UI Automation (Windows), `xdotool` (Linux), `synthetic` (test). |
| `SQUID_SCREEN_POLL_MS` | `screenPollIntervalMs` | `1000` | Screen text polling frequency in milliseconds. |
-| `SQUID_TERMINAL` | `terminalSource` | `off` | Enable terminal shell integration (`fifo`). |
+| `SQUID_TERMINAL` | `terminalSource` | `off` | Enable terminal shell & automation task integration (`fifo`). |
| `SQUID_TERMINAL_FIFO` | `terminalSourcePath` | â | Path to terminal FIFO or Windows Named Pipe (`\\.\pipe\squid-term`). |
-| `SQUID_EDITOR_SAVES` | `editorSaveSource` | `off` | Enable editor save tracking (`fifo`). |
+| `SQUID_EDITOR_SAVES` | `editorSaveSource` | `off` | Enable editor and document save tracking (`fifo`). |
| `SQUID_EDITOR_FIFO` | `editorSavePath` | â | Path to editor save FIFO or Windows Named Pipe (`\\.\pipe\squid-editor`). |
| `SQUID_BROWSER` | `browserSource` | `off` | Enable browser active tab tracking (`darwin` on macOS, or `synthetic`). |
| `SQUID_CONTROL` | `captureGateBackend` | `off` | Enable pause/resume gate (`fifo`). |
| `SQUID_CONTROL_FIFO` | `captureGatePath` | â | Path to pause gate FIFO or Windows Named Pipe (`\\.\pipe\squid-control`). |
-| `SQUID_EXCLUDE` | `excludeApplications` | â | Comma-separated list of application names to exclude (e.g. `1Password,Vault`). |
+| `SQUID_EXCLUDE` | `excludeApplications` | â | Comma-separated list of application names to exclude (e.g. `1Password,Bitwarden`). |
| `SQUID_RETENTION_HOURS`| `retentionHours` | `off` | Hours of activity events retained in SQLite at startup. |
---
## ð ïž Under the Hood: Architecture & Philosophy
-For engineers, contributors, and curious hackers, Squid is built with rigorous local-first and deterministic engineering principles.
+For engineers, contributors, and curious hackers, Squid is built with rigorous local-first and deterministic engineering principles:
```
ââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ
â Sensory Ingress Adapters â
-â Filesystem Screen Text Terminal Hook Editor Saves â
-âââââââââ¬âââââââââââââââ¬ââââââââââââââââ¬ââââââââââââââââââ¬ââââââââââââââââ
- â â â â
- ⌠⌠⌠âŒ
+â Filesystem Screen / UI Text Terminal & Scripts Document Savesâ
+âââââââââ¬âââââââââââââââ¬ââââââââââââââââ¬âââââââââââââââââââ¬âââââââââââââââ
+ â â â â
+ ⌠⌠⌠âŒ
ââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ
â Capture Policy (Exclusion & Credential Redaction) â
ââââââââââââââââââââââââââââââââââââ¬ââââââââââââââââââââââââââââââââââââââ
@@ -217,20 +231,20 @@ For engineers, contributors, and curious hackers, Squid is built with rigorous l
```
### 1. Ingress Boundary & Credential Redaction
-All events enter via [`src/capture-policy.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-cf8f03cb/src/capture-policy.ts). `RedactingCapturePolicy` deterministically scrubs API keys, AWS tokens, GitHub credentials, PEM blocks, and passwords before anything touches SQLite or memory. `ExcludingCapturePolicy` halts observation whenever blacklisted apps take the foreground.
+All events enter via [`src/capture-policy.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-b6252c25/src/capture-policy.ts). `RedactingCapturePolicy` deterministically scrubs API keys, AWS tokens, GitHub credentials, PEM blocks, and passwords before anything touches SQLite or memory. `ExcludingCapturePolicy` halts observation whenever blacklisted apps take the foreground.
### 2. Append-Only SQLite Event Store & Stable Ordering
-Events are stored in SQLite using WAL mode with `synchronous = NORMAL` ([`src/sqlite-event-store.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-cf8f03cb/src/sqlite-event-store.ts)). Events have canonical monotonic ordering ([`src/chronicle-ordering.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-cf8f03cb/src/chronicle-ordering.ts)), making offline replay, crash recovery, and state reconstruction 100% deterministic.
+Events are stored in SQLite using WAL mode with `synchronous = NORMAL` ([`src/sqlite-event-store.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-b6252c25/src/sqlite-event-store.ts)). Events have canonical monotonic ordering ([`src/chronicle-ordering.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-b6252c25/src/chronicle-ordering.ts)), making offline replay, crash recovery, and state reconstruction 100% deterministic.
### 3. Episodic World State
-Time gaps between bursts of activity delineate discrete episodes ([`src/episode.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-cf8f03cb/src/episode.ts)). Raw events are reduced into a compact `WorldState` snapshot ([`src/world-state.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-cf8f03cb/src/world-state.ts)). The agent inspects this world state rather than querying raw event logs.
+Time gaps between bursts of activity delineate discrete episodes ([`src/episode.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-b6252c25/src/episode.ts)). Raw events are reduced into a compact `WorldState` snapshot ([`src/world-state.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-b6252c25/src/world-state.ts)). The agent inspects this world state rather than querying raw event logs.
### 4. Attention Sliding Window & Fast Decision Curation
-- **Attention Window** ([`src/attention-window-extension.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-cf8f03cb/src/attention-window-extension.ts)): Before each turn, observations older than `attentionWindowMinutes` (default 15m) are trimmed from the working context, preventing context exhaustion over days of uptime.
-- **Decision Curator** ([`src/decision-curator-extension.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-cf8f03cb/src/decision-curator-extension.ts)): Uses a lightweight classifier (`/v1/systemone` via Jev or Kev) to filter non-essential turns. Fails open on timeout or network error so the agent never hangs.
+- **Attention Window** ([`src/attention-window-extension.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-b6252c25/src/attention-window-extension.ts)): Before each turn, observations older than `attentionWindowMinutes` (default 15m) are trimmed from the working context, preventing context exhaustion over days of uptime.
+- **Decision Curator** ([`src/decision-curator-extension.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-b6252c25/src/decision-curator-extension.ts)): Uses a lightweight classifier (`/v1/systemone` via Jev or Kev) to filter non-essential turns. Fails open on timeout or network error so the agent never hangs.
### 5. Unified Cross-Platform Transport
-[`src/endpoint-transport.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-cf8f03cb/src/endpoint-transport.ts) provides a uniform abstraction across operating systems:
+[`src/endpoint-transport.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-b6252c25/src/endpoint-transport.ts) provides a uniform abstraction across operating systems:
- **Unix**: Domain sockets for IPC, FIFOs (`mkfifo`) for shell and editor hooks.
- **Windows**: Full support for Named Pipes (`\\.\pipe\squid-panel`, `\\.\pipe\squid-control`), powered by `Bun.listen({ unix })`.
diff --git a/README_zh.md b/README_zh.md
index b87cdd4..e1496c7 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -1,8 +1,8 @@
-# ðŠ Squid â å
šå€©åæ¡é¢çº§èªäž» AI æºèœäœ
+# ðŠ Squid â æ¡é¢çº§å
šå€©å䞪人èªäž» AI æºèœäœ
- å
·æå
šå€©åæç¥äžæç»è®°å¿çèªäž»æ¡é¢äŒŽäŸ£
- éé»æç¥å·¥äœåº · 深床ç解äžäžæ · å
³é®æ¶å»èªäž»å³æ · äžåå
šç±äœ ææ§
+ å
·æå
šå±æç¥äžæç»æ
å¢è®°å¿ç䞪人èªäž»æ¡é¢äŒŽäŸ£
+ éé»æç¥å·¥äœæµ · 深床ç解跚åºçšäžäžæ · å
³é®æ¶å»äž»åšè¡¥äœ · 䞥å®éç§å°œåšææ§
@@ -14,7 +14,7 @@