((( Shellfish

The shell companion for Replit builders.

Think. Brief. Fix. Review. Manage. Think for free. Fix fast. Ship better. Ship while you sleep.

Built for Replit. Powered by Replit's Claude. Zero setup. Zero API keys.

 ____  _          _ _  __ _     _                          v0.2.3
/ ___|| |__   ___| | |/ _(_)___| |__                shellfish.computer
\___ \| '_ \ / _ \ | | |_| / __| '_ \                  built for replit
 ___) | | | |  __/ | |  _| \__ \ | | |
|____/|_| |_|\___|_|_|_| |_|___/_| |_|

think · brief · fix · review · manage · run `shellfish help`

Install

npm install -g shellfish.computer
npx playwright install chromium
# Linux: also run `sudo npx playwright install-deps chromium`

The npm package is shellfish.computer (the bare shellfish name on npm is owned by an unrelated CI/CD tool). The bin name is still shellfish — you type shellfish ... after install, same as ever.

That's it. Runs inside Replit. Uses Replit's Claude integration — no keys, no env vars for the default Claude REPL. Want a second opinion from Codex / Gemini / Grok? Bring your own API key for those (see think codex below).

Think · Brief · Fix · Review · Loop · Manage

Five pillars. One CLI.

🧠 Think — shellfish think

Claude in your shell. Free. Save agent credits for building.

Open a Claude REPL right in your terminal. Plan a feature, pressure-test an idea, debug out loud — without burning a single agent credit on prose.

shellfish think

🦐 Thinking Partner
Claude in your shell.
Thinking is free. Agent credits are for building.
Type 'exit' to close.
──────────────────────────────────────────────────

you ▸ how should I structure my supabase RLS policies for a multi-tenant app?

Conversation history lives in the session. Type exit, quit, or hit Ctrl-D / Ctrl-C to leave.

Second opinions — shellfish think codex|gemini|grok

Want a different model in the loop? Pick one. Claude stays free via Replit AI Integrations; the others are strictly bring-your-own-key:

| Subcommand | Provider | Required env var | | ----------------------- | ----------------- | ------------------ | | shellfish think | Claude (Anthropic) | provided by Replit | | shellfish think codex | OpenAI / GPT-5 | OPENAI_API_KEY | | shellfish think gemini| Google Gemini | GEMINI_API_KEY | | shellfish think grok | xAI Grok (live web) | XAI_API_KEY |

export OPENAI_API_KEY=sk-...
shellfish think codex

Same REPL, same history, same exits — just a different brain.

Council — shellfish think council

Fan one prompt out to every model with a key set, render each answer in its own panel, then have Claude write the final synthesis with a single clear recommendation.

shellfish think council "should I use server actions or a REST route here?"
echo "review my migration plan: ..." | shellfish think council

Members without a configured key are skipped (and listed in the welcome banner). Claude is required for the synthesis step.

📝 Brief — shellfish brief

Turn a rough idea into a paste-ready Replit-agent prompt.

Interactive 4-question interview, or fully non-interactive via flags / piped stdin. The output is structured markdown with ## Goal, ## Done looks like, ## Constraints, ## Files to touch, ## Notes — copy it straight into the agent chat.

# interactive
shellfish brief

# one-shot
shellfish brief --goal "add dark mode toggle" --done "persists across reloads" \
                --constraints "use existing Tailwind tokens"

# from stdin
echo "wire stripe checkout into the pricing page" | shellfish brief

🔧 Fix — shellfish connect · shellfish fix · shellfish watch · shellfish cache

Stuck connecting something? Goes fishing. Comes back with what you need.

shellfish connect <service>

Get exact, paste-ready steps to wire up an external service:

shellfish connect supabase
shellfish connect google-oauth     # aliases: google, googleoauth
shellfish connect google-workspace # aliases: gmail, drive, calendar, admin-sdk, workspace
shellfish connect google-sheets    # aliases: sheets, gsheets, googlesheets
shellfish connect google-docs      # aliases: docs, gdocs, googledocs
shellfish connect stripe
shellfish connect clerk            # aliases: clerkjs, clerk-auth
shellfish connect neon             # aliases: neondb, neon-postgres
shellfish connect notion           # alias:   notion-api
shellfish connect resend           # aliases: resend-email, resendemail
shellfish connect sendgrid         # aliases: send-grid, twilio-sendgrid
shellfish connect postmark         # alias: postmarkapp
shellfish connect mailgun          # alias: mail-gun
shellfish connect ses              # aliases: aws-ses, amazon-ses
shellfish connect nodemailer       # aliases: smtp, node-mailer
shellfish connect asana
shellfish connect box
shellfish connect calendly         # alias: cal
shellfish connect confluence
shellfish connect discord          # aliases: discord-bot, discordjs
shellfish connect dropbox
shellfish connect todoist
shellfish connect spotify
shellfish connect zendesk
shellfish connect elevenlabs       # aliases: eleven, eleven-labs, 11labs
shellfish connect figma
shellfish connect revenuecat       # aliases: revcat, revenue-cat
shellfish connect agentmail        # alias: agent-mail
shellfish connect firecrawl        # alias: firecrawl-api
shellfish connect apify            # aliases: apify-actors, apify-client
shellfish connect browserless      # aliases: browserless-api, browserless-io
shellfish connect scrapingbee      # aliases: bee, scraping-bee, scrapingbee-api
shellfish connect slack            # aliases: slack-api, slack-bot
shellfish connect github           # aliases: gh, github-api, octokit
shellfish connect linear           # aliases: linear-api, linear-graphql
shellfish connect jira             # aliases: atlassian-jira, atlassian
shellfish connect hubspot          # aliases: hubspot-api, hubspot-crm
shellfish connect twilio           # aliases: twilio-sms, twilio-voice
shellfish connect google-maps      # aliases: gmaps, maps, google-maps-platform
shellfish connect mapbox           # aliases: mb, mapbox-gl, mapbox-api
shellfish connect whatsapp         # aliases: meta-whatsapp, whatsapp-meta, whatsapp-cloud, whatsapp-business
shellfish connect whatsapp-twilio  # aliases: twilio-whatsapp, whatsapp-twilio-api
shellfish connect tiktok           # aliases: tiktok-api, tiktok-developers, tt
shellfish connect instagram        # aliases: ig, instagram-graph, instagram-api, ig-graph
shellfish connect facebook         # aliases: fb, facebook-graph, facebook-api, meta-graph
shellfish connect linkedin         # aliases: linkedin-api, linkedin-marketing, li
shellfish connect reddit           # aliases: reddit-api, snoowrap, reddit-oauth
shellfish connect twitter          # aliases: x, x-api, twitter-api, tweepy, x-twitter

Fetched docs are cached for 24 hours under ~/.shellfish/cache/, so re-running the same connect command is near-instant. Pass --fresh to bypass the cache:

shellfish connect stripe --fresh

Shellfish Memory

After every successful connect, Shellfish appends a short, structured entry to your project's REPLIT.md under a ## Shellfish Memory section so the Replit Agent automatically remembers what's been wired up:

## Shellfish Memory

- stripe: connected on 2026-05-01, env vars: STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
- clerk: connected on 2026-05-01, env vars: CLERK_SECRET_KEY

Re-running connect stripe updates the existing stripe line in place rather than appending a duplicate. Connecting a different service adds a new line under the same section without touching anything else in REPLIT.md. If REPLIT.md doesn't exist yet, Shellfish creates one containing only the Shellfish Memory section.

If you'd rather keep REPLIT.md to yourself, opt out per-run:

shellfish connect stripe --no-memory

shellfish fix [error]

Paste an error and get a one-line cause + numbered fix steps. If the error mentions a service Shellfish knows, it pulls live docs first for grounding. It also recognizes two common Replit pain points:

• CORS errors — diagnoses the wrong-origin / missing-credentials / missing-preflight cases against Replit's dev vs deployed domain split.
• Drizzle ORM errors — pulls live Drizzle docs so the diagnosis cites real Drizzle APIs.

Service hints take precedence over framework hints — a Supabase error that also mentions CORS still grounds against Supabase docs.

Before generating the prompt, shellfish fix quietly scans your local project for grounding context (best-effort, anything missing is silently skipped):

• Stack detection from package.json — primary framework / runtime cues and the package manager (e.g. Stack: Node + Express + Drizzle (pnpm)).
• Stack-trace excerpts — if the pasted error references files that exist in the project, a ~20-line window around the cited line for the top 1-3 frames (skips node_modules and dotfile dirs).
• Recent changes — git diff HEAD~1 and git status --porcelain, capped and clearly truncated when long.

Scanning runs in parallel with the docs fetch so it doesn't add wall-clock latency. When something useful is gathered you'll see a single dim line like 🦐 grounded in 2 files + recent diff. Pass --no-scan to skip the scan entirely.

shellfish fix "TypeError: supabase.from is not a function"

# Skip the local codebase scan:
shellfish fix --no-scan "TypeError: supabase.from is not a function"

# CORS:
shellfish fix "Access to fetch at 'https://api.example.com' from origin 'https://my-app.replit.app' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource."

# Drizzle:
shellfish fix 'DrizzleError: relation "users" does not exist'

# Or pipe a build/run log:
npm run dev 2>&1 | shellfish fix

shellfish env-check

Scan the project for required env vars and report which are set, missing, or set-but-empty. Reads .env.example / .env.sample / .env.template plus process.env.X and import.meta.env.X references in your source. Exits non-zero when anything required is missing — wire it into your dev workflow.

shellfish env-check

shellfish audit

Dependency-health snapshot for Node projects. Auto-detects npm / pnpm / yarn from the lockfile, verifies the lockfile is in sync with package.json, runs the manager's outdated and audit commands, and prints a brand-styled summary highlighting major-version drift and severity counts. Exits non-zero when there are critical or high security advisories, when the lockfile is out of sync with package.json, or when the package manager itself fails to run (e.g. not installed). Outdated packages alone never fail.

shellfish audit

shellfish checkpoint / shellfish rollback

Git-based safety net for "the agent broke something — back me up." Stays on the current branch and uses git reset --keep so uncommitted work that doesn't conflict is preserved. Confirms before any destructive action.

shellfish checkpoint                    # default name = timestamp
shellfish checkpoint before-refactor    # named checkpoint, tagged shellfish/before-refactor
shellfish rollback                      # list every shellfish checkpoint
shellfish rollback before-refactor      # restore the working tree to that checkpoint

shellfish watch [-- <cmd>...]

Tail your dev server (or any piped log stream) and auto-diagnose errors as they fire — no more notice error → copy → paste → run fix. Two ways to use it:

# Spawn mode: Shellfish runs your command, streams its output through to
# your terminal unchanged, and watches for errors in real time.
shellfish watch -- npm run dev
shellfish watch -- node server.js

# Pipe mode: Shellfish reads piped stdin instead.
npm run dev 2>&1 | shellfish watch

When Shellfish recognizes an error block (Node Error: + stack trace, Python Traceback, Vite/Next plugin errors, unhandled rejections), it prints 🦐 Error detected. Diagnosing..., runs the same fix pipeline (service detection + doc grounding) against the captured block, prints the paste-ready agent task, and resumes streaming the underlying process output. Repeats of the same error within ~30s are silently ignored so a single failure can't trigger a flood of diagnoses.

Flags:

• --quiet — suppress the 🦐 Error detected. Diagnosing... marker line (the final fix block still prints).
• --once — exit cleanly after the first diagnosis. Useful for one-shot scripts (shellfish watch --once -- node broken.js).

Ctrl-C cleanly forwards to the child process (when spawned) and exits the watcher.

shellfish cache

Inspect or clear the local docs cache (~/.shellfish/cache/).

shellfish cache list             # show each cached service, age, and size
shellfish cache prune            # remove only expired entries (keeps fresh ones)
shellfish cache clear            # remove every cached entry
shellfish cache clear stripe     # remove just one service's entries

The cache directory honors SHELLFISH_CACHE_DIR if you'd rather keep cached docs somewhere else.

🔍 Review — shellfish review <url> · shellfish perf <url>

Brutal honest feedback on your app. Formatted as Replit agent tasks.

Visit a deployed app, screenshot it, and get a brutally honest senior-designer scorecard with the top 3 paste-ready fixes:

shellfish review https://your-app.replit.app
shellfish review https://shellfish.computer

You'll see three score bars (COPY / DESIGN / UX), a green ✅ list of what's working, a red ❌ list of what needs fixing, and three cyan boxes — each one a fully-formed task you can paste straight into the Replit agent chat.

The whole point is the loop: run review → fix the top 3 → run review again → score goes up. Works on any public http(s) URL.

shellfish perf <url>

Same shape, but for speed instead of taste. Headless-Chromium loads the page, captures Navigation Timing + Resource Timing + FCP/LCP, and prints a performance scorecard with three paste-ready agent tasks for the biggest wins:

shellfish perf https://your-app.replit.app

Reports time-to-first-byte, FCP, LCP, total transfer size, request count, and the biggest render-blocking resources. Desktop viewport only for v1.

shellfish style <reference>

Pull a real design system out of any URL or screenshot — paste-ready tokens for the agent, plus a sticky design-memory line in REPLIT.md.

Hand it a URL or a local image and Shellfish will extract a full token set (palette with named roles, type scale, spacing, radii, shadows, motion) and render it in the right shape for your stack — Tailwind, Tailwind+shadcn, plain React, or Expo+NativeWind:

shellfish style https://linear.app
shellfish style https://stripe.com --stack tailwind
shellfish style ./inspiration.png
shellfish style ./mockup.png --no-memory
shellfish style https://shellfish.computer --fresh

Stack is auto-detected from your package.json and components.json. Override with --stack tailwind|shadcn|react|expo.

After every successful run, Shellfish upserts a compact ## Shellfish Design Memory section into your REPLIT.md so every future agent edit has something concrete to align to. Pass --no-memory to skip that write. URL renders are cached the same way connect caches docs — pass --fresh to bypass.

🔁 Loop — shellfish loop until

Hand off the boring fix-then-rerun cycle. Walk away. Come back to a green check.

Shellfish's first autonomous command. Point it at a check (tests, lint, typecheck — anything that exits non-zero on failure) and it will run the check, ask Claude to fix the first failing test, and re-run, looping until the check goes green or it hits a cap. Designed for the boring, recoverable failures: typos in tests, off-by-one boundaries, a renamed export that broke 30 callers — the stuff you don't want to do by hand at midnight.

shellfish loop until "pnpm test"
shellfish loop until                       # auto-detects from package.json scripts
shellfish loop until --max 5 --budget 0.50
shellfish loop until "pnpm typecheck && pnpm lint" --time 10m
shellfish loop stop                        # from another shell, kills a running loop

If you don't pass a command, Shellfish auto-detects one from your package.json scripts (test, then check, then ci) and invokes it via the right runner (pnpm/yarn/npm based on your lockfile).

Caps (hard, default-on)

• --max 20 iterations
• --budget 2 USD
• --time 30m wall clock

Hit any one → loop stops with a one-line summary that always looks like:

🦐 Stopped. 4 iterations, 2m elapsed, $0.0823 spent. Check passed. Next: run `shellfish review` to see how it looks

Safety, by default

• Refuses to start if your git tree is dirty (override with --no-checkpoint). You should always be able to git diff to see what the loop did.
• Holds a PID lock at .shellfish/loops/.lock so a second loop can't trample the first. Use shellfish loop stop from another shell to kill the running one.
• Stops automatically if the same error appears 3 iterations in a row, or if Claude makes zero file changes 3 iterations in a row. No infinite spin.
• Each iteration is a single, focused edit — designed to keep the diff reviewable, not to "rewrite everything until it passes".

Lessons (.shellfish/lessons.md) After a successful run Shellfish asks once for an optional "anything we should remember?" note. It's appended to .shellfish/lessons.md (dated, ~4KB cap with oldest entries trimmed first) and shown to Claude on every future loop run in this project. Project-specific muscle memory, no extra setup.

Run artifacts (.shellfish/loops/)

• {ISO-timestamp}.log — append-only structured log of every iteration
• last.summary.md — human-readable summary of the most recent run

Coming soon

• shellfish loop freeform — loop on a freeform goal (no test command — Claude judges its own progress).
• shellfish loop prd — loop against a PRD/spec file, ticking off acceptance criteria as it goes.

🤖 Manage — shellfish manage

Autonomous propose · execute · review · approve loop. Ship while you sleep.

Sets up a long-running loop in your repl that proposes small tasks, executes them with Claude (shell + read/write file + git tools), self-reviews the result, and either approves or asks you for sign-off — all gated by a policy file you control. Watch it on the live dashboard at /manage, approve risky moves from your phone.

# 1. write a starter policy
mkdir -p .shellfish
cat > .shellfish/manage.toml <<'TOML'
autonomy = "pause-on-risky"   # full | pause-on-risky | approve-each
max_usd = 5
max_minutes = 30
max_tasks = 8
review_threshold = 0.7
risky_actions = [
  "write:/lib/auth/**",
  "write:/.env*",
  "shell:rm -rf",
  "shell:git push",
]
blocked_commands = ["rm -rf /", "shutdown", "reboot"]
TOML

# 2. start a goal-mode run (the shorthand and the long form are equivalent)
shellfish manage "ship onboarding v2"
# same as: shellfish manage start --goal "ship onboarding v2"

# 3. watch + control
shellfish manage status
shellfish manage tail --follow
shellfish manage approve <approval-id> [--note "ship it"]
shellfish manage reject  <approval-id> [--note "scope creep"]
shellfish manage stop

Three backlog modes. Pick one with --mode:

• --mode goal --goal "<one-liner>" — Claude decomposes the goal into a small task queue.
• --mode roadmap — reads ROADMAP.md (or --roadmap <file>) and queues unchecked items in order.
• --mode discovery — scans the repo for TODO/FIXME/XXX markers and queues them by priority.

State is persisted. Every run, task, event, approval, review and spend snapshot lives in Postgres (manage_runs, manage_tasks, manage_events, manage_approvals, manage_reviews, manage_spend_snapshots) so the dashboard, the CLI and a fresh terminal all see the same truth. The runner is detached (pid file at .shellfish/manage.pid); kill it any time with shellfish manage stop or the kill button in the dashboard.

Safety rails.

• Every shell/write_file action is classified by lib/manager/policy.js (actionCategory()) and gated by gateAction(). With pause-on-risky, matches against risky_actions pause the run and create an approval row; with approve-each, every action requires sign-off; with full, only blocked_commands are blocked.
• The executor caps each task at MAX_TURNS=12 with loop detection.
• Spend is snapshotted every cycle and surfaced on the dashboard with a budget gauge — runs auto-pause when they hit max_usd / max_minutes / max_tasks.
• Nothing is force-pushed; tasks land on local git checkpoints (manage/<task-id>) so you can roll back any approved task with one git reset.

End-to-end smoke check from this repo:

./scripts/manage-demo.sh                                 # default goal
./scripts/manage-demo.sh /path/to/project "tighten copy" # custom

📱 Dispatch — approve from your phone via Discord

The same Manage approvals, delivered as a DM. Tap Approve / Reject / Reply in Discord without leaving the conversation.

Manage already pauses on risky actions and asks for sign-off. Dispatch delivers that ask to a phone you actually carry. The api-server hosts a small Discord bot that DMs you whenever an approval lands and renders three buttons: Approve, Reject, Reply… (Reply opens a modal so you can attach a note before approving). Buttons resolve the same manage_approvals row the dashboard and the CLI write to — first one to act wins, the message edits in place.

Pairing happens in the dashboard. Open /manage, find the Dispatch card, click get linking code, and DM the shellfish bot the printed /link <CODE> command in Discord. The code is 8 characters, single-use, 10-min TTL. The bot replies ✅ Linked and from then on every Manage run that hits a risky action will DM you the approval card. Unlink with one click on the same card.

The CLI is read-only — shellfish dispatch just reports the current pairing so you can confirm what's wired up:

shellfish dispatch
# → status:        linked
#   channel:       discord
#   discord user:  @you
#   linked since:  2026-04-30 17:24:08

# point at a non-default api-server
SHELLFISH_API_URL=http://localhost:8080/api shellfish dispatch

Server setup (one time, on the api-server). Set two env vars and restart:

• DISCORD_BOT_TOKEN — bot token from Discord Developer Portal → Bot. Required.
• DISCORD_CLIENT_ID — your application's client/app id. Optional; used to render an "open bot DM" deeplink in the dashboard.

Bot scopes when inviting: bot + applications.commands. The bot only needs DM access — no guild permissions required. With no token configured, the api-server boots normally and the dashboard shows the Dispatch card as disabled; nothing else changes.

How it works under the hood. The api-server runs a 2-second poller that watches manage_approvals for newly-inserted pending rows and sends a DM to the linked Discord account, recording the message id back on the approval row. Button clicks and modal submissions go through the same decideApprovalById() helper the dashboard and CLI use, so authorship is attributed (actor.via = "discord", handle = "@you") and the orchestrator unblocks the gated task immediately. Single-channel (Discord) and single-user (userId = "default") for v1; the schema is multi-channel / multi-user ready.

🐝 Swarm — shellfish swarm

Fan out a list of project briefs into a fleet of parallel autonomous agents.

shellfish swarm is the flagship buildathon feature: instead of running one agent overnight, you run a coordinated fleet and ship N builds in parallel — all tracked in the same database the manage dashboard reads.

Quick start

# 1. Write a briefs.yaml describing each build
cat > briefs.yaml <<'YAML'
- name: "Weather Dashboard"
  goal: "Build a weather dashboard using the OpenWeatherMap free API"
  constraints: "Use React and Tailwind CSS"
  tags: [react, api]

- name: "URL Shortener"
  goal: "Build a URL shortener with click analytics"
  tags: [backend, saas]

- name: "Pomodoro Timer"
  goal: "Build a Pomodoro timer with session history and streaks"
  constraints: "No backend — localStorage only"
  tags: [react, productivity]
YAML

# 2. Launch the fleet (up to 5 runs in parallel by default)
shellfish swarm start briefs.yaml

# 3. Check progress
shellfish swarm status

# 4. Stop everything if needed
shellfish swarm stop swm_<id>

Brief schema

Each brief is a YAML list item (or a JSON array object) with these fields:

| Field | Required | Description | | ------------- | -------- | ---------------------------------------------------------- | | name | ✅ | Short display name for the run | | goal | ✅ | One-sentence goal passed to the manage runner | | constraints | — | Extra requirements appended to the goal | | tags | — | List of labels (visible in swarm status) |

A JSON equivalent is also accepted:

[
  { "name": "Weather Dashboard", "goal": "Build a weather dashboard", "tags": ["react"] },
  { "name": "URL Shortener",     "goal": "Build a URL shortener with analytics" }
]

Concurrency

# Default: 5 parallel runs
shellfish swarm start briefs.yaml

# Dial up to burn more credits faster
shellfish swarm start briefs.yaml --concurrency 10

# Conservative (one at a time)
shellfish swarm start briefs.yaml --concurrency 1

The controller polls every few seconds; when a slot opens (a run finishes or is killed), the next queued brief launches automatically. The controller runs in the foreground — Ctrl-C detaches safely, runs continue in the background.

shellfish swarm status [swarm-id]

────────────────────────────────────────────────────
  shellfish swarm — status

  swm_abc1234567890ab  running   briefs: 8  concurrency: 5  started: 3m ago
    runs: 3 running  2 done  1 killed   tasks: done 14  pending 7

    id                   status     done   pending  elapsed  goal
    ────────────────────────────────────────────────────────────────────────────────
    run_aa112233…        running    4      2        12m      Build a weather dashboar…
    run_bb334455…        done       6      0        18m      Build a URL shortener wit…
    run_cc556677…        running    2      3        8m       Build a Pomodoro timer wi…

Omit the swarm id to list the 10 most recent swarms. Per-run details match shellfish manage status — you can also use shellfish manage tail <run-id> to follow a specific run's event stream.

shellfish swarm stop <swarm-id>

Marks the swarm as stopped and sends SIGTERM to every running agent. Runs that are already done or killed are unaffected.

How it works

Each brief becomes a manage start --goal "..." equivalent — a full manage_run row in the same manage_runs table, tagged with the swarm's swarm_id. From there it's indistinguishable from a standalone run:

• The same orchestrator loop (propose → execute → review → approve)
• The same approval flow (Discord DMs, /manage dashboard)
• The same event log (manage_events), readable via manage tail
• The same budget controls from .shellfish/manage.toml

The swarm layer is a thin scheduler: it reads briefs, creates runs, spawns background runner processes, and keeps the concurrency within the requested limit.

📊 Meter — shellfish meter

Live terminal credit-spend widget for Replit.

A live, full-screen terminal widget that shows your Replit credit spend in real time — session spend, last hour, today's spend, current burn rate, and how much runway is left at that pace. It refreshes every ~30 seconds.

shellfish meter --setup    # one-time: paste your Replit session cookie
shellfish meter            # live widget; Ctrl+C exits with a one-line summary
shellfish meter --once     # single snapshot to stdout — pipe it anywhere

How --setup works: open replit.com in your browser, open DevTools → Application → Cookies, copy your session cookie, then paste it into the prompt. Shellfish validates it against your Replit dashboard, then stores it locally at ~/.shellfish/meter-config.json with mode 0600 (owner read/write only). It never leaves your machine — every fetch is a direct request from your terminal to Replit, just like your browser.

If your cookie expires or Replit logs you out, you'll see a clear message pointing you back at shellfish meter --setup — no stack traces, no surprises.

Supported targets

connect <service> — alphabetized:

• connect agentmail
• connect apify
• connect asana
• connect box
• connect browserless
• connect calendly
• connect clerk
• connect confluence
• connect discord
• connect dropbox
• connect elevenlabs
• connect expo-eas (Expo / EAS Build + Submit + Update for React Native)
• connect figma
• connect firecrawl
• connect freshbooks (aliases: fresh-books, freshbooks-api)
• connect google-docs
• connect google-maps (aliases: gmaps, maps, google-maps-platform)
• connect google-oauth
• connect google-sheets
• connect google-workspace (Gmail, Drive, Calendar, Admin SDK)
• connect mailgun
• connect mapbox (aliases: mb, mapbox-gl, mapbox-api)
• connect neon
• connect nodemailer
• connect notion
• connect plaid
• connect play-console (Google Play Console — Android Play Store releases & API uploads)
• connect postmark
• connect quickbooks (aliases: qbo, intuit)
• connect resend
• connect revenuecat
• connect scrapingbee
• connect sendgrid
• connect ses
• connect spotify
• connect stripe
• connect supabase
• connect testflight (TestFlight + App Store Connect for iOS releases)
• connect todoist
• connect wave (aliases: waveapps, wave-apps, wave-accounting)
• connect xero (aliases: xero-accounting, xero-api)
• connect zendesk
• connect zoho-books (aliases: zoho, zohobooks, zoho-accounting)
• connect slack
• connect github
• connect linear
• connect jira
• connect hubspot
• connect twilio
• connect solana — Web3 & crypto: Solana via @solana/web3.js
• connect evm — Web3 & crypto: Ethereum / EVM chains via ethers or viem (aliases: ethers, viem, ethereum, wagmi)
• connect walletconnect — Web3 & crypto: WalletConnect / Reown AppKit wallet-connect modal (aliases: reown, appkit, wc)
• connect privy — Web3 & crypto: embedded-wallet auth + JWT verification (aliases: privy-io, embedded-wallets)
• connect whatsapp (Meta Cloud API)
• connect whatsapp-twilio
• connect tiktok
• connect instagram
• connect facebook
• connect linkedin
• connect reddit
• connect twitter (X)
• fix [error] — with built-in detection for every service above plus CORS and Drizzle ORM errors
• watch [-- <cmd>] — tail logs and auto-diagnose errors as they fire
• env-check — scan for required env vars and report what's missing or empty
• audit — dependency health snapshot (npm / pnpm / yarn auto-detected)
• checkpoint [name] — save a named git checkpoint
• rollback [name] — list checkpoints, or restore the working tree to one
• review <url> — brutal-judge scorecard for any deployed app
• perf <url> — performance scorecard (TTFB, FCP, LCP, weight) for any deployed app
• style <reference> — extract a design system from a URL or image, paste-ready tokens + REPLIT.md memory
• meter — live terminal credit-spend widget (run meter --setup first)
• play — offline ASCII fishing minigame (zero network, zero auth) for when the agent is overloaded
• cache list
• cache prune
• cache clear [service]

Changelog

v0.2.3 — Overnight runs & buildathon command

• Overnight / non-stop runs — Pro users can now let shellfish manage run unattended for up to 8 hours. The default policy switches to autonomy: full for Pro accounts so the runner powers through safe edits without pausing.
• Relaxed Pro guardrails — free-tier caps (3 tasks / 30 min) no longer apply to Pro users; their manage.toml settings are trusted as-is.
• Detached background runner — manage start now spawns a detached child process so closing the terminal doesn't kill the run.
• Replit Workflow registration — the runner registers itself in .replit on start so the platform can revive it after a container sleep or restart.
• shellfish buildathon "<idea>" — new command that wraps manage start with buildathon-friendly defaults (8 h cap, $10 spend ceiling, pause-on-risky autonomy, detached background) — go from a one-liner to a working demo by morning.

v0.2.2 and earlier

See git history.

Hack on it

git clone <repo-url> shellfish
cd shellfish
npm install
npx playwright install chromium
node index.js think

From the workspace root, pnpm shellfish <args> is the shortcut for running the local CLI (e.g. pnpm shellfish help, pnpm shellfish think).

License

MIT