# SLICC — Full Reference

> A browser-native AI agent for getting practical work done in and through the browser.

SLICC (Self-Licking Ice Cream Cone) is a browser-native AI agent that gives LLMs real capabilities: shell access, file manipulation, browser automation, and web app interaction — all running client-side in the browser. No server, no API keys, nothing to approve.

## Ice Cream Vocabulary

SLICC uses ice-cream terminology that maps directly to architecture:

| Term | Meaning | Technical |
|------|---------|-----------|
| Cone | Main agent | Full filesystem/tool access, orchestrates scoops |
| Scoops | Isolated sub-agents | Sandboxed filesystem, own shell and conversation |
| Licks | External events | Webhooks, cron jobs, signals from outside |
| Floats | Runtime environments | CLI, Chrome extension, Electron |
| Tray | Multi-float session | Multiple floats coordinated via hub |
| Sprinkles | UI enhancements | Interactive .shtml panels in chat or sidebars |

## Installation

### Quick Start (No Clone)
```
npx sliccy
```
Downloads latest release, launches Chrome, opens workspace. Requires Node >= 22.

### Global Installation
```
npm install -g sliccy
slicc
```

### From Source
```
git clone https://github.com/ai-ecoverse/slicc.git
cd slicc
npm install
npm start
```

### Chrome Extension
Available on the Chrome Web Store or build from source:
```
npm install
npm run build:extension
```
Load `dist/extension/` as unpacked extension in `chrome://extensions`.

### macOS Desktop App
Download DMG from GitHub Releases. Drag to Applications, double-click.

### Electron Apps
```
npm run dev:electron -- /Applications/Slack.app
```
Injects overlay shell into target Electron app.

## Three Deployment Modes

### 1. Standalone CLI
Express server launches Chrome, proxies CDP. Split layout: scoops sidebar + chat + terminal + files/memory. All state lives in IndexedDB; server is stateless relay.

### 2. Chrome Extension (Manifest V3)
Side panel (UI) ↔ Service worker (relay + CDP proxy) ↔ Offscreen document (agent engine). Agent survives side panel close.

### 3. Electron Float
CLI server in `--serve-only` mode. Injects overlay shell into target Electron app. Same core experience, overlay reinjected across navigation.

## Architecture Stack

```
Virtual Filesystem (LightningFS/IndexedDB)
  ↓
Shell (just-bash WASM + xterm.js)
  ↓
Git (isomorphic-git)
  ↓
Skills (SKILL.md package manager)
  ↓
CDP (Chrome DevTools Protocol client)
  ↓
Tools (file, bash, javascript, search)
  ↓
Core Agent (agent loop + streaming)
  ↓
Scoops Orchestrator (multi-agent coordination)
  ↓
UI (Chat + Terminal + Files + Memory panels)
  ↓
CLI / Extension / Electron (deployment runtimes)
```

## Shell Commands

### Standard Unix Commands (126)
ls, cat, echo, grep, sed, awk, find, sort, uniq, head, tail, cut, tr, wc, jq, tar, curl, mv, cp, rm, mkdir, rmdir, touch, chmod, diff, gzip, gunzip, printf, test, true, false, seq, date, sleep, env, export, read, cd, pwd, basename, dirname, ln, stat, du, df, whoami, hostname, ps, kill, wait, alias, unalias, source, eval, exec, set, unset, shift, getopts, xargs, tee, and more.

### Custom Supplemental Commands (17+)

| Command | Purpose |
|---------|---------|
| commands | List all available commands |
| which | Resolve command path |
| host | Show tray status + join URLs |
| oauth-token | Get OAuth access token for a provider |
| serve | Open VFS app directory in browser tab |
| open | Open URL or serve VFS file |
| imgcat | Display image inline in terminal |
| zip / unzip | Create/extract ZIP archives |
| sqlite3 | Execute SQLite queries |
| node -e | Execute JavaScript |
| python3 -c | Execute Python (via Pyodide) |
| webhook | Manage webhooks for licks |
| crontask | Schedule cron-driven licks |
| pdftk / pdf | PDF manipulation |
| convert / magick | Image conversion |
| playwright-cli | Browser automation (snapshot, click, fill, screenshot, cookies, tabs) |
| screencapture | Capture screen via browser API |
| upskill | Install skills from GitHub |
| sprinkle | Manage .shtml UI panels |
| git | Full git support (isomorphic-git) |

## Agent Tools

| Tool | Cone | Scoop | Purpose |
|------|------|-------|---------|
| bash | yes | yes | Full shell including browser automation commands |
| read_file | yes | yes (restricted) | Read from virtual filesystem |
| write_file | yes | yes (restricted) | Write to virtual filesystem |
| edit_file | yes | yes (restricted) | String replacement edit |
| javascript | yes | yes | Execute JS with VFS access |
| send_message | yes | yes | Send message to scoop queue |
| list_scoops | yes | no | List all scoops (cone-only) |
| scoop_scoop | yes | no | Create new scoop (cone-only) |
| feed_scoop | yes | no | Delegate task to scoop (cone-only) |
| drop_scoop | yes | no | Remove scoop (cone-only) |
| update_global_memory | yes | no | Update /shared/CLAUDE.md (cone-only) |

## Browser Automation

Via `playwright-cli`, `playwright`, or `puppeteer` shell commands:

- `open <url>` — Navigate to URL
- `snapshot` — Take accessibility snapshot of the page
- `click <ref>` — Click element by accessibility ref
- `fill <ref> <text>` — Fill text input
- `screenshot [--filename=path]` — Screenshot page
- `cookie-set/delete <name> <value>` — Manage cookies
- `tab-new/tab-list/tab-focus` — Manage browser tabs
- `teleport --start=<regex> --return=<regex>` — Cross-origin auth flows

## Virtual Filesystem

POSIX-like filesystem backed by LightningFS (IndexedDB).

- All paths absolute, normalized
- All operations async (Promise-based)
- Scoops get sandboxed access via RestrictedFS: only `/scoops/{name}/` + `/shared/`
- JavaScript tool has full VFS access: `fs.readFile`, `fs.writeFile`, `fs.readDir`, `fs.mkdir`, `fs.rm`, `fs.stat`, `fs.exists`

## Multi-Agent System (Scoops)

### Cone (Main Agent)
- Full filesystem and tool access
- Orchestrates scoops via scoop_scoop, feed_scoop, drop_scoop
- Persisted conversation history

### Scoops (Sub-Agents)
- Sandboxed filesystem: `/scoops/{name}/` + `/shared/`
- Separate conversation history
- Independent shell context
- Sequential message queue
- Can be triggered by webhooks and cron (licks)

### Delegation Pattern
```
scoop_scoop name="analyzer"
feed_scoop scoop_name="analyzer" prompt="Self-contained task description..."
# Scoops work in parallel
# Check /scoops/{name}/CLAUDE.md for updates
```

## External Events (Licks)

### Webhooks
```
webhook create /my-endpoint
webhook list
webhook delete <id>
```
External POST to webhook endpoint triggers assigned scoop.

### Cron Tasks
```
crontask add "daily-backup" "0 2 * * *" backup-scoop "Backup all files"
```
Scheduled licks dispatch to scoops without human intervention.

## Skills System

Reusable agent capabilities packaged as:
- `SKILL.md` — Instructions for the agent
- `manifest.yaml` — Dependencies, conflicts, files
- `.jsh` scripts — Executable shell commands

Install skills:
```
upskill owner/repo        # From GitHub
upskill clawhub:name      # From ClawHub
upskill search "query"    # Search for skills
```

Skills are auto-loaded into the agent system prompt.

## Sprinkles (Interactive UI)

`.shtml` files rendered as interactive UI panels. Agents can generate them inline in chat via ```shtml code blocks. Bridge API available:

```javascript
window.__slicc_bridge__.lick({ action: 'run', command: 'ls' });
window.__slicc_bridge__.setState({ key: 'value' });
```

## API Keys & Providers

SLICC is BYOT (bring your own tokens). Supported providers:
- Anthropic (Claude)
- AWS Bedrock (standard + CAMP)
- Adobe AEM
- OpenAI-compatible providers

Provider configured via UI or `providers.json`.

## Storage

| Database | Purpose |
|----------|---------|
| slicc-fs | Virtual filesystem (LightningFS) |
| agent-sessions | Conversation history per scoop |
| slicc-groups | Orchestrator state (scoops, messages, tasks, webhooks, cron) |

Context compaction triggers at ~183K tokens: LLM generates structured summary, replaces older messages.

## Package Structure

| Package | Purpose |
|---------|---------|
| packages/webapp/ | Browser app core (UI, VFS, shell, CDP, tools, scoops) |
| packages/chrome-extension/ | Manifest V3 extension entry points |
| packages/node-server/ | CLI/Electron: Chrome launcher, CDP proxy |
| packages/cloudflare-worker/ | Tray hub (session coordination) |
| packages/vfs-root/ | Default VFS content |
| packages/swift-launcher/ | macOS SwiftUI launcher (Sliccstart) |
| packages/swift-server/ | macOS Hummingbird server |

## Related Projects

SLICC is part of the AI Ecoverse (https://github.com/ai-ecoverse):
- yolo — Worktree-friendly CLI launcher for AI workflows
- upskill — Skill installer (built into SLICC)
- ai-aligned-git — Git guardrails for AI agents
- ai-aligned-gh — GitHub guardrails for AI agents

## Links

- Website: https://www.sliccy.com
- Source: https://github.com/ai-ecoverse/slicc
- npm: https://www.npmjs.com/package/sliccy
- License: Apache-2.0