Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/5235aa-web--pebbleagent/badge.svg)](/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

i

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.

  1. <div align="center">
  2. <img src="assets/logo.png" alt="PEBBLE-AGENT" width="720">
  3. **A light,extensible desktop AI agent with tools, skills, MCP servers, a self-maintained code knowledge base, and cross-session memory.**
  4. [![checks](https://img.shields.io/github/actions/workflow/status/5235aa-web/pebbleagent/checks.yml?style=flat-square&label=checks&labelColor=1f1f1f&color=00E676)](https://github.com/5235aa-web/pebbleagent/actions/workflows/checks.yml)
  5. [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-CE93D8?style=flat-square&labelColor=1f1f1f)](LICENSE)
  6. [![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-44AAFF?style=flat-square&labelColor=1f1f1f)](https://www.python.org/)
  7. [![Vue 3](https://img.shields.io/badge/Vue-3-00E676?style=flat-square&labelColor=1f1f1f)](https://vuejs.org/)
  8. [![Tauri 2](https://img.shields.io/badge/Tauri-2-FF6699?style=flat-square&labelColor=1f1f1f)](https://tauri.app/)
  9. [![Platform: Windows](https://img.shields.io/badge/Platform-Windows-8A92A6?style=flat-square&labelColor=1f1f1f)](#)
  10. [![Platform: macOS](https://img.shields.io/badge/Platform-macOS-8A92A6?style=flat-square&labelColor=1f1f1f&logo=apple&logoColor=ffffff)](#)
  11. </div>
  12. > **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.
  13. >
  14. > <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>
  15. ## Features
  16. - **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.
  17. - **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.
  18. - **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.
  19. - **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.
  20. - **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.
  21. - **Real-time cost tracking.** Per-model pricing with peak/off-peak tiers (including Chinese statutory holidays) and cache-hit accounting, updated live per conversation.
  22. - **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.
  23. - **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.
  24. - **Full UI theming.** Pick any color and the whole palette adapts instantly across the entire interface.
  25. - **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.
  26. ## Screenshots
  27. <p>
  28. <img src="assets/png1.png" alt="PebbleAgent desktop interface" width="1000">
  29. </p>
  30. <p>
  31. <img src="assets/png2.png" alt="PebbleAgent desktop interface, conversation view" width="1000">
  32. </p>
  33. <p>
  34. <img src="assets/png3.png" alt="PebbleAgent desktop interface, current release" width="1000">
  35. </p>
  36. ## Architecture
  37. ```mermaid
  38. flowchart LR
  39. UI["Vue 3 + Pinia<br/>(Tauri 2 webview)"] -->|"WebSocket · JSON-RPC 2.0"| GW["Python Gateway"]
  40. GW --> AG["Agent Core"]
  41. AG --> TL["Tool System"]
  42. AG --> MCP["MCP Servers"]
  43. AG --> LLM["LLM Providers"]
  44. GW --> DB[("SQLite")]
  45. ```
  46. ## Getting Started
  47. ### Prerequisites
  48. - Windows 10/11 (64-bit) for the desktop shell, or macOS for web mode
  49. - Python 3.11+
  50. - Node.js 18+ (for the frontend and npx-based MCP servers)
  51. - Rust toolchain (only needed to build the desktop shell)
  52. ### Run from source
  53. ```bash
  54. git clone <your-repo-url>
  55. cd <repo-folder>
  56. pip install -r requirements.txt
  57. cd frontend
  58. npm install
  59. cd ..
  60. ```
  61. `requirements.txt` is the core set, enough to start the backend and chat. The
  62. optional set adds `pypdf` for reading PDF attachments, `psutil` for CPU/memory
  63. details and `playwright` for optional browser automation; install
  64. it with `pip install -r requirements-optional.txt`.
  65. Then launch both services with the provided script:
  66. ```bash
  67. start_gui.bat
  68. ```
  69. This starts the Python backend (`ws://127.0.0.1:19876`) and the Vite dev server (`http://localhost:5180`).
  70. On macOS the two services are started separately:
  71. ```bash
  72. chmod +x start_backend.sh
  73. ./start_backend.sh
  74. ```
  75. ```bash
  76. cd frontend
  77. npm run dev
  78. ```
  79. Then open http://localhost:5180. The dev server injects the gateway token into the
  80. page, so nothing else has to be configured. The `powershell` tool is not offered on
  81. macOS; `execute_code` (`language="bash"`) covers shell execution. The desktop shell cannot be built
  82. there yet, so web mode is how it runs.
  83. To run the desktop shell in development instead, start the backend first and then:
  84. ```bash
  85. cd frontend
  86. npx tauri dev
  87. ```
  88. ### Build the desktop app
  89. > **Just want to run it?** Windows users who want the app rather than the build
  90. > should grab the latest installer from
  91. > [Releases](https://github.com/5235aa-web/pebbleagent/releases/latest). It
  92. > already bundles the Python backend, so none of the steps below are needed.
  93. > This section is Windows-only. The sidecar management in
  94. > `frontend/src-tauri/src/lib.rs` is built on Win32 APIs, so the shell does not
  95. > compile on macOS. Web mode above needs none of it.
  96. 1. Package the backend with PyInstaller:
  97. ```bash
  98. pyinstaller pebble-backend.spec
  99. ```
  100. 2. Copy the artifact next to the Tauri shell (sidecar naming requires the target triple):
  101. ```bash
  102. copy dist\pebble-backend.exe frontend\src-tauri\binaries\pebble-backend-x86_64-pc-windows-msvc.exe
  103. ```
  104. 3. Build the desktop bundle:
  105. ```bash
  106. cd frontend
  107. npx tauri build
  108. ```
  109. ## Configuration
  110. All runtime data lives in `%USERPROFILE%\.pebble\` (override with the `PEBBLE_HOME` environment variable).
  111. - **LLM providers** — providers, API keys, models, and reasoning effort are configured in `llm_providers.json` or from the in-app settings.
  112. - **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.
  113. - **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.
  114. - **Permissions** — modes and `tool:pattern` rules live in `permission_rules.json`; the path whitelist in `path_whitelist.json`.
  115. - **Pricing** — the per-model price table (with peak/off-peak tiers) is in `model_pricing.json`; holiday data in `cn_holidays.json`.
  116. ## Project Structure
  117. ```
  118. gateway/ Python WebSocket gateway (JSON-RPC, sessions, permissions)
  119. agent_core/ Agent core (chat service, built-in tools, orchestration, experience ledger, snapshots)
  120. skills/ Bundled skills (ckb, frontend-design)
  121. knowledgesource/ Code knowledge base (chaptered)
  122. frontend/ Orbit frontend (Vue 3) + Tauri 2 desktop shell
  123. tests/ Standalone verification tests (python tests/run_all.py)
  124. ```
  125. ## Tests
  126. Standalone verification tests live in `tests/` and need no framework — each file runs on its own and exits non-zero on failure:
  127. ```bash
  128. python tests/run_all.py # Python tests (tool policy, compaction, billing, ...)
  129. node tests/run_all.mjs # JS tests (fold algorithm, WS recovery, UI formulas, ...)
  130. ```
  131. 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`).
  132. ## Credits
  133. PebbleAgent bundles 2 core skills (`ckb` and `frontend-design`). Third-party
  134. attributions are listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
  135. ## License
  136. Licensed under the [GNU Affero General Public License v3.0](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.