Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add skills/nicobailon/surf-cli/surf-codebasenpx skills add nicobailon/surf-cli --skill surf-codebasegit clone --depth 1 https://github.com/nicobailon/surf-cliWhat it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5 | $0.00042 | $0.00956 |
| Opus 5 | $0.00021 | $0.00478 |
| Sonnet 5 | $0.00008 | $0.00191 |
| Haiku 4.5 | $0.00004 | $0.00096 |
Grade A, and why
surf-codebase scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 106 lines — stays where its author put it; the contents beside it link to each section on GitHub.
surf-cli Codebase
Architecture
cli.cjs --socket:/tmp/surf.sock--> host.cjs --native-msg--> service-worker/index.ts --CDP/chrome-APIs--> browser
Add CLI Command
- Add to
TOOLSin native/cli.cjs:158 (args, opts, examples) - Add handler in src/service-worker/index.ts:50
handleMessage()switch - CDP op? → add method src/cdp/controller.ts:60
- DOM interaction? → add handler src/content/accessibility-tree.ts:99
Add CDP Operation
- Add method to
CDPControllerclass src/cdp/controller.ts:60 - Use
this.send(tabId, "Domain.method", params) - Handle events in
handleCDPEvent()if needed
Core Files
src/service-worker/index.ts (~2500L) - Central msg router, CDP ops, screenshot cache, tab registry
- Msg types: EXECUTE_CLICK, EXECUTE_TYPE, READ_PAGE, EXECUTE_SCREENSHOT
- Screenshot cache: generateScreenshotId(), cacheScreenshot(), getScreenshot()
- Tab names: tabNameRegistry Map<name,tabId>
src/cdp/controller.ts (~1000L) - CDP wrapper, CDPController class
- Mouse: click(), rightClick(), doubleClick(), hover(), drag()
- Keyboard: type(), pressKey(), pressKeyChord()
- Screenshots: captureScreenshot(), captureRegion()
- Network/Console: enableNetworkTracking(), getNetworkRequests(), getResponseBody(), subscribeToNetwork(), enableConsoleTracking(), getConsoleMessages()
- Emulation: emulateNetwork(), emulateCPU(), emulateGeolocation()
src/content/accessibility-tree.ts (~1900L) - Content script, generates a11y tree YAML, element interactions
- Handlers: GENERATE_ACCESSIBILITY_TREE, CLICK_ELEMENT, FORM_INPUT, GET_ELEMENT_COORDINATES, WAIT_FOR_ELEMENT, WAIT_FOR_URL
- Element refs: e1, e2... in window.__piRefs for stable references
native/cli.cjs (~2100L) - CLI parser, socket client
- TOOLS: command defs with args/opts
- ALIASES: shortcut→command map
- AUTO_SCREENSHOT_TOOLS: commands that auto-capture
- parseArgs(), sendRequest()
native/host.cjs (~2100L) - Socket server, AI integration
- handleToolRequest(): main dispatcher
- mapToolToMessage(): tool→extension msg converter
- queueAiRequest(): AI request serialization
- AI clients: chatgptClient, geminiClient, perplexityClient
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 2d ago First seen · 106 lines · 42 tokens per session scan A 072b3a3ddded
surf-codebase is a skill published in the GitHub repository nicobailon/surf-cli (606 stars, last pushed 2d ago), licensed MIT. It adds 42 tokens to every session and 956 once invoked, about $0.0002 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
Other skills, from other repositories
build-plugin
Complete plugin development workflow: build, test, icon, troubleshoot, and setup. Use when the user wants to build a plugin, create a plugin, troubleshoot issues, add icons, or install/configure plugins. Triggers on: build plugin, create plugin, develop plugin, new plugin, plugin icon, troubleshoot, debug, setup…
bump-version
Bump package versions across all platform packages and plugins in lockstep. Use when the user wants to bump versions, update versions, or prepare a release. Triggers on: bump version, bump versions, version bump, update version, prepare release.
ralph
Plan work and generate ralph task files for autonomous execution. Use when the user wants to plan tasks, create a prd, run ralph, or fix a batch of issues. Triggers on: ralph, create tasks, plan this, run ralph, prd.
devloop
Drive Devloop — browser + dev-server on one correlated timeline (web, plus native iOS/Android Expo apps) — by calling its MCP tools as shell commands via mcporter. Use when Devloop's MCP server isn't wired into this agent directly (e.g. a sandboxed or enterprise setup that blocks MCP) but you can run shell commands.
release
Cut a new devloop release — bump the version across all files, update the changelog, commit, tag, and trigger the publish workflow. Use when asked to "cut a release", "ship a version", or "publish a new version" of devloop-mcp.
site-audit
Use when user asks to audit a website, review all pages, check for broken links, capture full site state, or do a comprehensive product review.