<p align="center"><img src="assets/banner.png" alt="Agentic Bookmark Manager" width="100%"></p>

<h1 align="center"><img src="extension/icons/icon48.png" width="32" align="top"> Agentic Bookmark Manager</h1>

<p align="center"><b>Provide coding agents the full suite to collaborate on your bookmarks.</b><br>
Live. Project-based. Local only. No data retention.</p>

---

With no setup beyond loading the extension, your browser becomes the place where you and your coding agents **index your knowledge together, in sync**. Your agent researches something and the sources land in your bookmarks bar, filed under the task, ready for you to read and audit. You drop a link in your Inbox, and your agent files it where it belongs. Your tab groups follow your projects. Everything changes live, with no restart, and syncs to your phone through your browser's own sync.

## Why

- **Seamless knowledge transfer.** Agents file research into `Read this > yy.mm.dd - Task name` with every source, so you're never in the dark about where an answer came from.
- **Easy-to-track templates.** Project folders with *In use* (what the project is wired to) and *Considering* (what was evaluated). Dated research folders. An agent-kept *Index*.
- **Agents that organize with you.** Search, health checks, duplicate cleanup, favicon loading, snapshots and one-command restore. Nothing is ever hard-deleted.
- **Tab groups, project-based.** One click (or one tool call) groups every open tab under its project, based on your bookmark folders. Open a folder as a group, or save a group as a folder.
- **Works with your preferences.** Your locked folders stay yours. Agents work in the spaces you give them.
- **Local only.** No accounts, no servers, no analytics. The optional agent bridge listens on `127.0.0.1` only.

## Install

1. **Extension:** Chrome Web Store (coming soon), or `chrome://extensions` / `brave://extensions` → Developer mode → **Load unpacked** → `extension/`.
2. That's it for the side panel. Click the toolbar icon to open it: search, project-based tab grouping, templates, health check, icon loading.

### Connect a coding agent (optional)

Requires [uv](https://docs.astral.sh/uv/) (it fetches Python 3.15 and the MCP SDK on first run).

**MCP** (Claude Code, Cursor, Zed, any MCP client):

```json
{
  "mcpServers": {
    "bookmarks": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/agentic-bookmark-manager", "mcp_server.py"]
    }
  }
}
```

Claude Code: `claude mcp add bookmarks -- uv run --directory /path/to/agentic-bookmark-manager mcp_server.py`

The server ships instructions explaining the conventions, so an agent with no prior context knows how to use it.

**CLI:** `uv run abm.py --help`

```
uv run abm.py search convex
uv run abm.py read-this "Understanding File Structure Architecture" "Diátaxis" https://diataxis.fr/ --note "why"
uv run abm.py organize --dry
uv run abm.py project "New Client" --under MTS
uv run abm.py doctor --fix
```

## How it works

```
agent --MCP/CLI--> abm.py --> queue --> server.py (127.0.0.1:47817) <--long-poll-- extension --> bookmarks / tab groups
                                                                                   \--> live tree back to the agent
```

- **extension/**: Manifest V3. Side panel works on its own; when the local bridge is running it also applies agent operations and streams the live bookmark tree back.
- **server.py**: stdlib HTTP server bound to `127.0.0.1`. Requests need header `X-ABM: 1`, so web pages can't drive it.
- **abm.py**: the CLI (stdlib only). Starts the server on demand. If the browser is closed, operations wait and apply when it opens.
- **mcp_server.py**: MCP server (official Python SDK) exposing every command as a tool.

## Conventions

| Folder | Who writes | Purpose |
|---|---|---|
| Your project folders | You (agents add on request) | Root = hot links; *In use*; *Considering* |
| `Read this > yy.mm.dd - Task` | Agent | Research for you, with sources and a `_notes` page |
| `Index` | Agent | Everything not locked down; finished Read-this folders move to `Index > Research` |
| `Inbox` | You | Drop links for your agent to file |
| `Other bookmarks > _Trash` | Agent | Where "deleted" things go. Nothing is hard-deleted |

## Tests

- `python test_bridge.py`: protocol, header guard, CLI (no browser).
- `python test_e2e.py`: 23 checks in a real Chromium browser with a throwaway profile on port 47818 (never touches your bookmarks).
- `uv run test_mcp.py`: MCP handshake, tool list, a live call.
- `python package.py`: builds the Web Store zip in `dist/`.

## Issues

Please file issues and ideas at **[github.com/jgharbieh/agentic-bookmark-manager/issues](https://github.com/jgharbieh/agentic-bookmark-manager/issues)**.

## Privacy

Everything stays on your device. See [PRIVACY.md](PRIVACY.md).

## License

MIT