tabstack-cli: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

tabstack is a Go CLI client for the Tabstack AI API: browser automation, web research, and structured extraction/generation from any URL. It is a hand-written HTTP client (no generated code) wrapped in a Cobra command tree.

Commands

make build       # build into ./bin/tabstack (version stamped from `git describe`)
make install     # install into $GOPATH/bin
make run ARGS="extract markdown --url ..."
make lint        # gofmt -w . then go vet ./...
make test        # go test ./...
make help        # list all targets

Version is injected via -ldflags -X .../cmd.version=$(VERSION); VERSION comes from git describe --tags --always --dirty, falling back to dev.

Tests live alongside each package (*_test.go); GitHub Actions runs gofmt/vet/build/test on push and PRs (.github/workflows/ci.yml). client.WithHTTPClient injects a mock *http.Client for tests. scripts/smoke-test.sh (make smoke) exercises every command against the live API.

Architecture

Three layers, each in its own package:

• cmd/tabstack/main.go: entry point; builds the root command and runs it through fang.Execute (charmbracelet/fang), which renders styled help, errors, version output, and adds completion/man subcommands. fang prints errors itself and returns them, so main keeps owning the exit-code mapping: it checks for any error implementing Code() int (the coded interface) and exits with that code, else maps cobra usage errors to 2, else 1. Version is handed to fang via cmd.Version() (stamped by -ldflags). (Lives in its own dir so go install .../cmd/tabstack produces a tabstack binary.)
• cmd/: Cobra command tree, one file per endpoint group (agent, extract, generate, schema, auth, keys). Each leaf command only builds its request and calls the client. The auth flow is split across auth.go (status/logout/sessions), login.go (the OAuth flow and loopback callback), switch.go (org switching), keysetup.go (the shared key-setup prompt), and orgs.go (org selector resolution).
• internal/client/: the HTTP client and per-endpoint request/response types for the product host. Sends the org-scoped API key, never the session.
• internal/console/: the client for the auth and management host (console.tabstack.ai): /oauth/* (PKCE authorize URL, code exchange, refresh) and /cli/* (me, organizations, api_keys, sessions, logout). Sends the user-scoped session token, never an API key. Split by host on purpose so the wrong credential cannot reach the wrong endpoint.
• internal/schemas/: fetches the public tabstack-schemas GitHub repo and manages the local schema store (schema pull/schema list). Kept separate from client: it talks to raw.githubusercontent.com unauthenticated, so it must never see the API bearer token. Mirrors client's injectable-http.Client pattern (schemas.WithHTTPClient) for tests.
• internal/config/: credential and base-URL resolution. Also resolves SchemasDir() (the default schema pull destination, alongside the config file under the tabstack config home).
• internal/ui/: output rendering (pretty vs JSON), styles, spinner.