pebbleagent
An extensible desktop AI agent
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/5235aa-web/pebbleagent with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/5235aa-web/pebbleagent'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/5235aa-web--pebbleagent)HTML
<a href="/listings/5235aa-web--pebbleagent"><img src="/api/listings/5235aa-web--pebbleagent/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Prerequisites
- Windows 10/11 (64-bit), the only supported platform for now - Python 3.11+ - Node.js 18+ (for the frontend and npx-based MCP servers) - Rust toolchain (only needed to build the desktop shell)
Run from source
git clone <your-repo-url> cd <repo-folder> pip install -r requirements.txt cd ui-gui-vue3 npm install cd ..
Then launch both services with the provided script:
start_gui.bat
This starts the Python backend (`ws://127.0.0.1:19876`) and the Vite dev server (`http://localhost:5174`).
To run the desktop shell in development instead, start the backend first and then:
cd ui-gui-vue3 npx tauri dev
Build the desktop app
1. Package the backend with PyInstaller:
pyinstaller pebble-backend.spec
2. Copy the artifact next to the Tauri shell (sidecar naming requires the target triple):
copy dist\pebble-backend.exe ui-gui-vue3\src-tauri\binaries\pebble-backend-x86_64-pc-windows-msvc.exe
3. Build the desktop bundle:
cd ui-gui-vue3 npx tauri build
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 188 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <div align="center">
- <img src="assets/logo.png" alt="PEBBLE-AGENT" width="720">
- **A light,extensible desktop AI agent with tools, skills, MCP servers, a self-maintained code knowledge base, and cross-session memory.**
- [](https://github.com/5235aa-web/pebbleagent/actions/workflows/checks.yml)
- [](LICENSE)
- [](https://www.python.org/)
- [](https://vuejs.org/)
- [](https://tauri.app/)
- [](#)
- [](#)
- </div>
- > **Platform support:** Windows 10/11 (64-bit) is the tested platform, and the only one that can build the desktop shell. The backend and the web UI also run on macOS, where the shell is unavailable because its Tauri sidecar management is written against Win32 APIs. Linux is untested.
- >
- > <sub>macOS has not been run by the author, who has no Apple machine. It should work on MacOS theoretically — and if it does not, please open an issue.</sub>
- ## Features
- - **Code Knowledge Base (CKB).** The agent indexes your repository into a chaptered knowledge base, verifies it against the source, and keeps it in sync as the project evolves.
- - **Cross-session experience ledger.** Corrections, constraints, and preferences you express during work become evidence-backed entries in a local SQLite ledger. Later turns recall the relevant ones by full-text relevance plus tool and path context, and superseded entries are retired automatically. Capture and recall run on rules, not extra model calls.
- - **Snapshot & rollback.** Every write is snapshotted before it happens; diffs are tracked per file, and you can roll back a single file or an entire change set — with an undo for the rollback itself.
- - **Permission & audit system.** Three permission modes (manual, auto, read-only), rule sets with `tool:pattern` matching, a path whitelist, fail-closed checks, and a tamper-evident audit log (chained checksums) for every sensitive operation.
- - **Skills and MCP servers.** Two bundled skills (`ckb` and `frontend-design`) load on demand; MCP servers over stdio, SSE, HTTP, or WebSocket are installed with sha256 verification and approved per project. Both are extensible from the installed app with no source build required, and you do not have to touch a file yourself: ask the agent to add a skill or an MCP server and it writes the `SKILL.md` under `~/.pebble/skills/<name>/` or the `mcpServers` entry in `~/.pebble/.mcp.json` for you. A user skill with the same name overrides the bundled one, and a new MCP entry waits in the MCP panel until you approve it before anything is launched.
- - **Real-time cost tracking.** Per-model pricing with peak/off-peak tiers (including Chinese statutory holidays) and cache-hit accounting, updated live per conversation.
- - **HTML preview with feedback bridge.** Generated HTML pages render in a sandboxed preview; click any element to leave a comment, and the agent iterates on the page from your annotations.
- - **Streaming agent chat with full execution visibility.** Reasoning, tool calls, file changes, and results unfold as a step-by-step timeline instead of a black box.
- - **Full UI theming.** Pick any color and the whole palette adapts instantly across the entire interface.
- - **Desktop-grade shell.** A frameless Tauri 2 window, a WebSocket JSON-RPC 2.0 protocol, and a self-contained Python backend shipped as a sidecar.
- ## Screenshots
- <p>
- <img src="assets/png1.png" alt="PebbleAgent desktop interface" width="1000">
- </p>
- <p>
- <img src="assets/png2.png" alt="PebbleAgent desktop interface, conversation view" width="1000">
- </p>
- <p>
- <img src="assets/png3.png" alt="PebbleAgent desktop interface, current release" width="1000">
- </p>
- ## Architecture
- ```mermaid
- flowchart LR
- UI["Vue 3 + Pinia<br/>(Tauri 2 webview)"] -->|"WebSocket · JSON-RPC 2.0"| GW["Python Gateway"]
- GW --> AG["Agent Core"]
- AG --> TL["Tool System"]
- AG --> MCP["MCP Servers"]
- AG --> LLM["LLM Providers"]
- GW --> DB[("SQLite")]
- ```
- ## Getting Started
- ### Prerequisites
- - Windows 10/11 (64-bit) for the desktop shell, or macOS for web mode
- - Python 3.11+
- - Node.js 18+ (for the frontend and npx-based MCP servers)
- - Rust toolchain (only needed to build the desktop shell)
- ### Run from source
- ```bash
- git clone <your-repo-url>
- cd <repo-folder>
- pip install -r requirements.txt
- cd frontend
- npm install
- cd ..
- ```
- `requirements.txt` is the core set, enough to start the backend and chat. The
- optional set adds `pypdf` for reading PDF attachments, `psutil` for CPU/memory
- details and `playwright` for optional browser automation; install
- it with `pip install -r requirements-optional.txt`.
- Then launch both services with the provided script:
- ```bash
- start_gui.bat
- ```
- This starts the Python backend (`ws://127.0.0.1:19876`) and the Vite dev server (`http://localhost:5180`).
- On macOS the two services are started separately:
- ```bash
- chmod +x start_backend.sh
- ./start_backend.sh
- ```
- ```bash
- cd frontend
- npm run dev
- ```
- Then open http://localhost:5180. The dev server injects the gateway token into the
- page, so nothing else has to be configured. The `powershell` tool is not offered on
- macOS; `execute_code` (`language="bash"`) covers shell execution. The desktop shell cannot be built
- there yet, so web mode is how it runs.
- To run the desktop shell in development instead, start the backend first and then:
- ```bash
- cd frontend
- npx tauri dev
- ```
- ### Build the desktop app
- > **Just want to run it?** Windows users who want the app rather than the build
- > should grab the latest installer from
- > [Releases](https://github.com/5235aa-web/pebbleagent/releases/latest). It
- > already bundles the Python backend, so none of the steps below are needed.
- > This section is Windows-only. The sidecar management in
- > `frontend/src-tauri/src/lib.rs` is built on Win32 APIs, so the shell does not
- > compile on macOS. Web mode above needs none of it.
- 1. Package the backend with PyInstaller:
- ```bash
- pyinstaller pebble-backend.spec
- ```
- 2. Copy the artifact next to the Tauri shell (sidecar naming requires the target triple):
- ```bash
- copy dist\pebble-backend.exe frontend\src-tauri\binaries\pebble-backend-x86_64-pc-windows-msvc.exe
- ```
- 3. Build the desktop bundle:
- ```bash
- cd frontend
- npx tauri build
- ```
- ## Configuration
- All runtime data lives in `%USERPROFILE%\.pebble\` (override with the `PEBBLE_HOME` environment variable).
- - **LLM providers** — providers, API keys, models, and reasoning effort are configured in `llm_providers.json` or from the in-app settings.
- - **Skills** — bundled skills ship inside the app. Ask the agent to add one and it writes `~/.pebble/skills/<name>/SKILL.md`; a user skill with the same name overrides the bundled copy.
- - **MCP servers** — the MCP panel installs and manages servers; tokens and executable paths are stored in `~/.pebble/.mcp.json`. Ask the agent to add a server and it writes the entry, which then appears in the panel and waits for your approval before it is launched.
- - **Permissions** — modes and `tool:pattern` rules live in `permission_rules.json`; the path whitelist in `path_whitelist.json`.
- - **Pricing** — the per-model price table (with peak/off-peak tiers) is in `model_pricing.json`; holiday data in `cn_holidays.json`.
- ## Project Structure
- ```
- gateway/ Python WebSocket gateway (JSON-RPC, sessions, permissions)
- agent_core/ Agent core (chat service, built-in tools, orchestration, experience ledger, snapshots)
- skills/ Bundled skills (ckb, frontend-design)
- knowledgesource/ Code knowledge base (chaptered)
- frontend/ Orbit frontend (Vue 3) + Tauri 2 desktop shell
- tests/ Standalone verification tests (python tests/run_all.py)
- ```
- ## Tests
- Standalone verification tests live in `tests/` and need no framework — each file runs on its own and exits non-zero on failure:
- ```bash
- python tests/run_all.py # Python tests (tool policy, compaction, billing, ...)
- node tests/run_all.mjs # JS tests (fold algorithm, WS recovery, UI formulas, ...)
- ```
- Three billing/holiday regression scripts (`peb_check_*.py`) sit at the repo root and follow the same exit-code convention. All of the above, plus a full `compileall` syntax check and a `vue-tsc` type check, run in CI on every push (`.github/workflows/checks.yml`).
- ## Credits
- PebbleAgent bundles 2 core skills (`ckb` and `frontend-design`). Third-party
- attributions are listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
- ## License
- Licensed under the [GNU Affero General Public License v3.0](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.