loopshouse

The Loops House CLI — authenticate, browse hackathons, ideate with AI, query sponsor knowledge graphs, and submit projects from your terminal or an AI agent. Built with incur, so the same definitions power a CLI, an MCP server, and an agent skill.

Install

One command sets everything up for a hackathon — installs the CLI globally, writes the event's agent skill into your coding agents (Claude Code + the .agents standard), and signs you in:

npx loopshouse add <hackathon-slug>

Re-run it any time to refresh the skill with the event's latest sponsors and deadlines. Or install manually:

npm i -g loopshouse
# or run from this repo:
bun run bin/loops.ts --help

Quick start

loops auth login --provider github     # or --provider google, or --email [email protected]
loops hackathon ideate --hackathonSlug <slug> -m "give me a project idea"
loops hackathon ideate --hackathonSlug <slug> -m "go deeper on idea 2"   # session continues automatically
loops knowledge query --hackathonSlug <slug> -s <sponsor> -q "how do I use the sponsor's SDK?"
loops project create --hackathonSlug <slug> --name "My Project" --repoUrl https://github.com/me/proj
loops project get --hackathonSlug <slug>
loops credits --hackathonSlug <slug>

The CLI is deliberately scoped to one hackathon at a time (no cross-hackathon listings); ideator conversations persist per hackathon in ~/.loops/sessions/.

Tip: every hackathon's playground has a "Use the skill" tab with the exact npx loopshouse add command. Append a sponsor slug (npx loopshouse add <slug> <sponsorSlug>) to install a skill focused on that sponsor's bounties, docs, and judging criteria instead.

Commands

| Group | Commands | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------- | | root | add <slug> [sponsorSlug] (interactive setup: CLI install/update, skill into agents, auth) | | auth | login, verify, status, logout | | hackathon | ideate (1 credit/turn; stateful session, --withProject, --new), session (show/--clear), submit | | project | get (your one project for a hackathon), create, update (PATCH — only passed fields change; no project id, yours is resolved) | | knowledge | query (1 credit/query — graph-RAG evidence from a sponsor's docs) | | artifact | list, save, update, remove (ideation scratchpad) | | root | credits (remaining agent credits), evaluate (per-sponsor evaluator prompt; your project auto-included) |

Authentication

Auth uses Supabase Auth against the Loops platform. Three flows:

| Flow | Command | | ------------ | --------------------------------------------------------------------------------------------- | | GitHub OAuth | loops auth login --provider github | | Google OAuth | loops auth login --provider google | | Email OTP | loops auth login --email [email protected] then loops auth verify --email [email protected] --code 123456 |

OAuth runs a localhost callback server (default port 54321, --port to change), opens your browser, and exchanges the PKCE code for a session. Tokens are stored at ~/.loops/credentials.json (mode 0600) and refreshed automatically on each command.

Agent surfaces

loops --mcp          # start as an MCP stdio server
loops mcp add        # register the MCP server with your agent
loops skills add     # generate + install skill files
loops --llms         # print the machine-readable command manifest

Configuration

| Env var | Default | Purpose | | ------------------------- | ----------------------------------- | -------------------- | | LOOPS_PLATFORM_URL | https://loops-platform.vercel.app | Platform API origin | | LOOPS_SUPABASE_URL | (baked) | Supabase project URL | | LOOPS_SUPABASE_ANON_KEY | (baked) | Supabase anon key |

Point these at http://localhost:3000 + your local Supabase to develop against a local stack.

Develop

bun install
bun run bin/loops.ts <args>   # run from source
bun run build                 # bundle to dist/loops.js
bun run typecheck             # tsc --noEmit