logbook/Docs

Getting started

This guide walks a human from a cold start to a working logbook: creating an account, standing up your team's organization, running the onboarding wizard, filing your first log, and inviting teammates. It is the human path. For wiring a coding agent to logbook over MCP, see Connecting agents.

Logbook (logbook.gvy.ai) is a shared team backlog. Humans sign in through Clerk; a Clerk Organization is your tenant, and projects nest inside it. Each project is one isolated board with its own items, labels, GitHub mapping, and agent connection URL.

The shape of an account

Three nested concepts, from outside in:

  • Organization — your team, the tenant boundary. All billing, membership, and API keys are org-level. In logbook's Clerk setup there is no personal account: every signed-in user acts inside exactly one active organization.
  • Project — one board inside the org (for example Groovy, Billing, a side project). Items, labels, PR history, and the MCP connection URL are all scoped to a single project. A project has a URL-safe slug derived from its name; the slug is globally unique and appears in its connection URL.
  • Item (a "log") — one unit of work on a board, referenced as LOG-N.

Numbering restarts per project: the first item you file in any project is LOG-1, regardless of how many items other projects hold. Note that the ref prefix is always LOG- — it does not change per project; only the number is project-local.

Step 1 — Create your account

Go to logbook.gvy.ai. New users land on the sign-up page (/sign-up), which renders Clerk's <SignUp> component. Existing users use the sign-in page (/sign-in). Authentication, password rules, email verification, and any social or SSO providers are handled entirely by Clerk — logbook does not store passwords.

After you authenticate for the first time, logbook lazily provisions a local user record mirrored from your Clerk identity (name and primary email). This mirror is what every board attribution, assignment, and inbox notification is keyed to. The email logbook uses is your Clerk primary email address — the one you signed in with.

Step 2 — Choose or create your organization

Logbook runs Clerk in organization-only mode (no personal workspace). If you sign in without an active organization — you just signed up, or you left your last org — you are routed to /select-org, which renders Clerk's <OrganizationList> with personal accounts hidden.

Here you either:

  • Create an organization — name it after your team or company. You become its owner. This is the tenant that will hold all your projects.
  • Select an existing organization — if a teammate already created one and invited you, accept the invitation (it arrives by email) and pick it here.

Selecting or creating an org sends you to the board (/). If your org has no projects yet, you are forwarded into the onboarding wizard.

Step 3 — The onboarding wizard

A brand-new organization with no projects opens the full-page wizard at /onboarding. It has five steps, shown in the top rail: Project, GitHub, Connect, Labels, Invite. The left pane is the input you fill; the right pane previews what you are configuring.

3.1 Project

Name your first project — for example Groovy, Freelance, or Side project. The project is created the moment you click Continue (not at the end of the wizard), so its board, slug, labels, and agent token all exist from this point on. If you go back and edit the name before finishing, the project is renamed in place.

3.2 GitHub

Answer whether this project is tied to a GitHub repository:

  • Yes, it has a GitHub repo — logbook will wire a webhook so that merged pull requests automatically cross linked items off the board. You may paste the repository URL (github.com/owner/name) so it can be mapped for you; this field is optional.
  • No repo (or it's private) — no webhook is set up. Items are marked done by hand. The connect prompt in the next step tells your agent it is in manual mode so it does not wait for a PR merge that will never come.

You must pick one option before continuing. See the GitHub webhook section below for what the webhook actually does.

3.3 Connect

The wizard shows a one-paste setup prompt for Claude Code and the project's API token (shown once — re-issue it later from Settings if you lose it). The prompt, pasted into Claude Code from inside the repository you want to track, does three things in order: connects the logbook MCP server scoped to this project, creates the GitHub webhook (only in the "yes, has repo" variant), and registers the repo with the project via the link_repo MCP tool.

You can complete onboarding without connecting an agent now and do it later from Settings → Connect Claude Code. The full agent-connection reference, including the exact command and .mcp.json shapes, is in Connecting agents.

3.4 Labels

Labels are a managed taxonomy, not free-form tags: items may only use labels that exist in this set, and both the web pickers and the agent's MCP tools draw from it. The wizard preselects a starter set — front-end, back-end, bug, product, auth, infra — which you can toggle off or extend with your own. Custom labels are lowercased and spaces become hyphens (Design System becomes design-system). You can change the taxonomy any time in Settings → Labels.

3.5 Invite

Add teammate email addresses to invite them into the organization as members. Each gets a Clerk email invitation to join the org; they then see this board and can claim work. You can add several, skip the step entirely, and invite more later from Settings → Team. Invitations are best-effort here: a duplicate or malformed address is silently skipped rather than blocking setup.

Use the exact email each teammate will sign in with. Assignments, attributions, and inbox notifications are keyed to the mirrored Clerk primary email, so an invite to an address they never sign in under will not connect to their board identity. If in doubt, invite the address they use for GitHub or their work SSO.

Finishing

Clicking Finish setup seeds the labels you chose, maps the repo (if you supplied a URL), sends the invitations, and drops you on the real board with a short interactive walkthrough overlaid on top.

Step 4 — The board walkthrough and your first log

The first time you reach the board after onboarding, a five-step walkthrough runs over the (still empty) board with mock cards so you can see how a working board behaves. It covers:

  1. The columns — work moves left to right through Backlog, In progress, and Done. Stuck is a hard stop that flags work needing help.
  2. Cards carry context — each item holds subtasks, attached documents, PR links, and assignees, all of which agents read and update over MCP.
  3. Claim by clicking — assign a card to yourself with one click.
  4. Filter by teammate — toggle a person in the team row to see just their work.
  5. You're set up — the walkthrough ends with a copyable prompt to confirm your agent connection.

The mock data is ephemeral and never written to the database. Dismiss the walkthrough with Skip tour or Go to board at any point; it will not reappear.

Filing your first item

Two ways to create your first real log:

  • From the board (human path). Use the board's item-creation UI. Every item needs a title; a problem statement, description, priority, labels, and assignees are optional. New items land in Backlog.

  • From your agent (recommended for confirming the connection). If you connected Claude Code, paste the walkthrough's test prompt:

    Create a test logbook item titled "Hello logbook" so I can confirm the
connection works.

    The agent calls the create_item MCP tool. A log created through MCP is attributed to you as its author, while the write itself is stamped claude (<your name>) in the activity feed so agent edits are distinguishable from human ones.

Once you have items on the board, move them by claiming and updating status: claiming an item assigns it to you and moves it to In progress; marking it Done crosses it off. When you finish work, write a short resolution — these accumulate into the project's history.

Inviting teammates later

Beyond the onboarding step, invite people any time from Settings → Team:

  1. Open Settings (from the shell) and scroll to the Team section.
  2. It lists current organization members with their roles and any pending invitations.
  3. Enter a teammate's email and click Send invite. They receive a Clerk invitation to join the org as a member.

Unlike the best-effort onboarding invites, this path surfaces errors directly — for example a free-plan member cap or a duplicate invitation — so you can see and act on them. Pending invitations can be revoked from the same section with the × button.

As with onboarding, invite the exact email the teammate signs in with. Board attribution and history resolve through the mirrored Clerk primary email, so matching the invited address to their real sign-in identity is what keeps "who did what" correct over time.

Switching and creating projects

The project switcher is the toggle in the top-left of the shell, showing the active project's name. Click it to:

  • Switch projects — pick any project in your org. This sets the active project (stored in a cookie scoped to your org) and re-renders the board. You only ever see projects belonging to your active organization.
  • Create a new project — click + New project, name it, and confirm. The project is created, made active, and a setup modal appears with a fresh connect-Claude-Code prompt and a one-time token so you can wire an agent to the new board immediately.

Each project is fully independent:

  • Its own LOG-N numbering — a new project's first item is LOG-1 even if another project already has LOG-500.
  • Its own connection URL — https://logbook.gvy.ai/api/mcp/<project-slug>. The same org API key works for every project; the URL is what fixes which board a connection writes to. See Connecting agents.
  • Its own labels, GitHub mapping, and webhook secret.

Manage a project from Settings: rename it, delete it (which removes all its items, PRs, and labels — this cannot be undone), manage its labels, map GitHub repos, and re-issue its setup prompt.

Plans and limits

New organizations start on the free plan:

  • 1 project per organization.
  • 50 logs total, for the lifetime of the org. The counter counts logs created; archiving does not refund quota.

Attempting to create a second project, or to file a log past the 50th, is blocked with an upgrade prompt rather than failing silently. The pro plan lifts both limits and is purchased through Stripe; the upgrade path lives in Settings. Reads, updates, notes, tasks, documents, status changes, and archiving are never gated — a capped org keeps full access to everything it has already created.

Billing is only enforced once Stripe is configured for the deployment. Until then every limit passes, so a self-hosted or pre-launch instance behaves as unlimited.

GitHub: PR merges cross items off

If you connected a repository, logbook records its pull-request events and crosses items off automatically. When a PR that a logbook item links to is merged, logbook:

  • sets the item's status to Done,
  • writes a default resolution noting the PR number, title, and who merged it (never overwriting a resolution you wrote yourself), and
  • records which files the PR changed, so the history_for_files agent tool can later report what shaped a given path.

Each project has its own webhook secret, shown in that project's setup prompt. The webhook payload URL is https://logbook.gvy.ai/api/webhooks/github for every project; the secret is what routes and authenticates events to the right board. If you skipped GitHub during onboarding, you can map a repo later from Settings → GitHub repos by adding it as owner/name and pointing a repo (or org) webhook at the payload URL with that project's secret.

Where to go next

  • Connecting agents — the full reference for API keys, connection URLs, .mcp.json and claude mcp add shapes, monorepo setups, legacy tokens, and the security model.