Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
**Gitdog** is an AI-powered GitHub issue and discussion assistant.

- Repository-aware issue and discussion formatting, answers, and maintainer tagging
- Claude Sonnet 5.5 generation with GPT-6.1 Sol fallback (see [docs/ai-models.md](docs/ai-models.md))
- Claude Opus 5.5 generation with GPT-6.1 Sol fallback (see [docs/ai-models.md](docs/ai-models.md))
- Keyword repository index plus AI repository tools (search, read file) for code search
- Private workspace per user
- Free and Pro token quotas with optional prepaid token packs
Expand Down
33 changes: 32 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,24 @@ organized, how to run it locally and what a pull request needs.
| `e2e/` | Opt-in end-to-end runners against a development backend |
| `docs/` | Conventions, GitHub App setup and AI model notes |

## Tech stack

| Layer | Technology |
| -------- | -------------------------------------------------------------------- |
| Frontend | React 19, TypeScript, Vite, Tailwind CSS, react-i18next (en, ko, ja) |
| Backend | Convex |
| AI | Claude Opus 5.5 with GPT-6.1 Sol fallback; users' own keys optional |
| GitHub | GitHub App (OAuth, webhooks, repository access) |
| Payments | Lemon Squeezy |
| Hosting | Firebase Hosting |

## How it works

```text
GitHub webhook ─▶ Convex ─▶ repository index (keyword search)
│
▼
Claude Sonnet 5.5 (GPT-6.1 Sol fallback)
Claude Opus 5.5 (GPT-6.1 Sol fallback)
│
▼
draft reply or review ─▶ approval ─▶ GitHub comment / PR review
Expand All @@ -43,6 +54,18 @@ bun run dev # web app and Convex together
A development GitHub App is required for repository features; follow
[docs/github-app-setup.md](docs/github-app-setup.md).

## Commands

| Command | Purpose |
| ---------------------- | ----------------------------------------------- |
| `bun run dev` | Run the web app and Convex dev backend together |
| `bun run typecheck` | Type-check the web app, backend and e2e runners |
| `bun run lint` | ESLint across the monorepo |
| `bun run format:check` | Prettier check |
| `bun run test` | Web and backend test suites |
| `bun run test:cli` | CLI test suite |
| `bun run check:api` | Verify the CLI API catalog matches the backend |

## Checks

Run these before opening a pull request:
Expand All @@ -67,6 +90,14 @@ reports drift). For CLI changes, run `bun run typecheck:cli && bun run test:cli`
- Follow [docs/convention.md](docs/convention.md) and [CLAUDE.md](CLAUDE.md) for
code style.

## Documentation

- [AI models and pricing](docs/ai-models.md): routing, quota weights and usage
accounting
- [GitHub App setup](docs/github-app-setup.md)
- [Code conventions](docs/convention.md)
- [CLI reference](packages/cli/docs/REFERENCE.md)

## Security

Please do not open public issues for security problems. Email
Expand Down
156 changes: 63 additions & 93 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,8 @@
## Why Gitdog

Maintainers answer the same questions, triage vague reports and review routine
changes every day. Gitdog indexes your repository and drafts the work for you —
with the actual code as evidence, not generic advice.
changes every day. Gitdog indexes your repository and drafts the work for you,
with the actual code as evidence instead of generic advice.

| | What it does |
| ------------------------ | --------------------------------------------------------------------------------------- |
Expand All @@ -54,6 +54,20 @@ with the actual code as evidence, not generic advice.
| **Your own AI keys** | Run generation on your Anthropic or OpenAI key, encrypted at rest and never shown again |
| **Team workspace** | Share projects with members and keep per-project settings and usage in one place |

## Get started

**On the web**: sign in with GitHub at [gitdog.dev](https://gitdog.dev), install
the GitHub App and connect a repository.

**From the terminal**: the [`gitdog` CLI](packages/cli) manages projects,
settings, approvals and pull request reviews.

```sh
npx gitdog@latest login
npx gitdog@latest init owner/repo
npx gitdog@latest tickets pending
```

## How it works

```mermaid
Expand All @@ -67,21 +81,21 @@ flowchart LR
```

1. **Connect** a repository through the Gitdog GitHub App.
2. **Index** — Gitdog builds a searchable index of your code and keeps it in
sync with the default branch.
3. **Draft** — new issues, discussions and pull requests get a reply or review
2. **Index**: Gitdog builds a searchable index of your code and keeps it in sync
with the default branch.
3. **Draft**: new issues, discussions and pull requests get a reply or review
grounded in the indexed source.
4. **Approve** — review the draft in Gitdog or the CLI, then publish it. A pull
request review with no findings needs no approval: it posts at once and, when
every changed file was reviewed and no Gitdog thread is open, approves the
reviewed commit. A later push, including updating the branch, withdraws that
approval until `@gitdogbot review` reviews the new commits.
4. **Approve**: review the draft in Gitdog or the CLI, then publish it.

A pull request review with no findings needs no approval. It posts at once and,
when every changed file was reviewed and no Gitdog thread is open, approves the
reviewed commit. A later push, including updating the branch, withdraws that
approval until the new commits are reviewed.

## Commands
## Pull request commands

Gitdog reviews a pull request once, when it is opened or marked ready for
review. After that, the pull request author or a collaborator asks for more in
a pull request comment, or from the CLI:
review. After that, ask for more in a pull request comment or from the CLI:

| Pull request comment | CLI | What it does |
| ------------------------ | ------------------------------------------- | ------------------------------------------------ |
Expand All @@ -90,90 +104,35 @@ a pull request comment, or from the CLI:
| `@gitdogbot resolve` | `gitdog reviews resolve <ticket-id>` | Resolves every Gitdog review thread |
| `@gitdogbot help` | `gitdog reviews --help` | Lists the commands |

A command is a comment line that starts with the mention, or follows another
review bot's command on the same line (`@coderabbitai review @gitdogbot
review`), in the pull request conversation; replies inside a review thread are
not read. `@gitdog` works as shorthand, but it also notifies the GitHub user
of that name, so `@gitdogbot` is preferred. While a review runs, Gitdog keeps
one status comment on the pull request up to date: reviewing, ready for
approval, reviewed, or why it could not finish. Collaborators can run
every command; the pull request author, who may work from a fork, can run all
but a full review. A review that failed or ran out of tokens can be requested
again, and pull requests opened by bots such as Dependabot are not reviewed.
- **Where**: a comment line in the pull request conversation that starts with
the mention, or follows another review bot's command on the same line
(`@coderabbitai review @gitdogbot review`). Replies inside a review thread
are not read.
- **Who**: collaborators can run every command. The pull request author, who
may work from a fork, can run all but `full review`.
- **`@gitdog`** works as shorthand, but it also notifies the GitHub user of that
name, so `@gitdogbot` is preferred.
- **Status**: while a review runs, one status comment on the pull request shows
whether it is reviewing, waiting for approval, reviewed, or why it could not
finish. A review that failed or ran out of tokens can be requested again. For
automatic reviews, Gitdog posts at most one failure comment a day per pull
request.
- **Limits**: someone who sends more than 10 commands an hour or 40 a day to
one repository is paused there for 24 hours. Pull requests opened by bots
such as Dependabot are not reviewed.

In an issue or discussion, mention `@gitdogbot` with a question to get a reply
grounded in the repository. When a review cannot finish, for example because the account ran out of tokens, its status comment says why; for automatic reviews Gitdog posts at most one such comment a day per pull request. Someone who sends more than 10 commands
an hour or 40 a day to one repository is paused there for 24 hours.

## Get started

**On the web** — sign in with GitHub at [gitdog.dev](https://gitdog.dev),
install the GitHub App and connect a repository. Try Gitdog with 100K one-time
trial tokens, then use your own Anthropic or OpenAI API key or Pro; no credit
card required.

**From the terminal** — the [`gitdog` CLI](packages/cli) manages projects,
settings, approvals and pull request reviews:

```sh
npx gitdog@latest login
npx gitdog@latest init owner/repo
npx gitdog@latest tickets pending
```

## Repository layout

This is a monorepo managed with bun workspaces.

| Path | Description |
| ------------------------------- | -------------------------------------------------------------------------- |
| [`src/`](src) | Web app — React 19, TypeScript, Tailwind CSS |
| [`convex/`](convex) | Backend — Convex functions, GitHub App, AI workflows and billing |
| [`packages/cli/`](packages/cli) | The `gitdog` CLI, published to [npm](https://www.npmjs.com/package/gitdog) |
| [`docs/`](docs) | Conventions, GitHub App setup and AI model notes |
grounded in the repository.

## Development
## Plans

Requires Node.js 26 (`nvm use`) and Bun 1.4.4.
Start with 100K one-time trial tokens, no credit card required. After that, use
Pro (2.4M tokens a month), prepaid token packs, or your own Anthropic or OpenAI
API key. Gitdog runs on Claude Opus 5.5, and each Opus token counts as 2 Gitdog
tokens. Work on your own key never uses Gitdog tokens. See
[AI models and pricing](docs/ai-models.md).

```sh
bun install
cp .env.example .env.local
bun run dev
```

| Command | Purpose |
| ------------------- | ----------------------------------------------- |
| `bun run dev` | Run the web app and Convex dev backend together |
| `bun run typecheck` | Type-check the web app, backend and e2e runners |
| `bun run lint` | ESLint across the monorepo |
| `bun run test` | Web and backend test suites |
| `bun run test:cli` | CLI test suite |
| `bun run check:api` | Verify the CLI API catalog matches the backend |

See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.

## Tech stack

| Layer | Technology |
| -------- | -------------------------------------------------------------------- |
| Frontend | React 19, TypeScript, Vite, Tailwind CSS, react-i18next (en, ko, ja) |
| Backend | Convex |
| AI | Claude Sonnet 5.5 with GPT-6.1 Sol fallback; your own key optional |
| GitHub | GitHub App (OAuth, webhooks, repository access) |
| Payments | Lemon Squeezy |
| Hosting | Firebase Hosting |

## Documentation

- [AI models and pricing](docs/ai-models.md)
- [GitHub App setup](docs/github-app-setup.md)
- [Code conventions](docs/convention.md)
- [CLI reference](packages/cli/docs/REFERENCE.md)

## Security

### Your Anthropic and OpenAI keys
## Your Anthropic and OpenAI keys

If you bring your own provider key, this is exactly how Gitdog handles it:

Expand Down Expand Up @@ -203,7 +162,18 @@ If you bring your own provider key, this is exactly how Gitdog handles it:
not cap it. Anyone who can open issues or pull requests on a connected public
repository can trigger generation, so set a spend limit with the provider.

### Reporting
## Documentation

- [CLI reference](packages/cli/docs/REFERENCE.md)
- [AI models and pricing](docs/ai-models.md)
- [GitHub App setup](docs/github-app-setup.md)

## Contributing

Development setup, repository layout and checks are in
[CONTRIBUTING.md](CONTRIBUTING.md).

## Security

Please report security issues privately to [hyo@hyo.dev](mailto:hyo@hyo.dev)
instead of opening a public issue.
Expand Down
29 changes: 26 additions & 3 deletions convex/_ai/chatBilling.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import { internal } from "../_generated/api";
import { RESERVATION_QUOTA_WEIGHT } from "./config";
import { chatRequestBytes } from "./requestSize";
import { ChatProviderRequestError } from "./providerErrors";
import { CreditFallbackProvider } from "./providers";
Expand Down Expand Up @@ -189,6 +190,10 @@ function parseChatResultCheckpoint(
(typeof value.providerRequestId !== "string" ||
!value.providerRequestId ||
value.providerRequestId.length > 512)) ||
(value.servedModelId !== undefined &&
(typeof value.servedModelId !== "string" ||
!value.servedModelId ||
value.servedModelId.length > 128)) ||
(value.historyContent !== undefined &&
!hasValidCheckpointHistory(value.historyContent)) ||
(value.toolUse !== undefined && !hasValidCheckpointToolUse(value.toolUse))
Expand All @@ -199,7 +204,8 @@ function parseChatResultCheckpoint(
expectedOutcome &&
(value.usage.promptTokens !== expectedOutcome.inputTokens ||
value.usage.completionTokens !== expectedOutcome.outputTokens ||
value.providerRequestId !== expectedOutcome.providerRequestId)
value.providerRequestId !== expectedOutcome.providerRequestId ||
value.servedModelId !== expectedOutcome.servedModel)
) {
throw new Error("AI chat result checkpoint usage mismatch");
}
Expand Down Expand Up @@ -295,6 +301,7 @@ type ChatSettlementOutcome =
inputTokens: number;
outputTokens: number;
providerRequestId?: string;
servedModel?: string;
}
| { kind: "known_not_billed"; providerRequestId?: string };

Expand All @@ -304,6 +311,7 @@ const chatSettlementOutcomeValidator = v.union(
inputTokens: v.number(),
outputTokens: v.number(),
providerRequestId: v.optional(v.string()),
servedModel: v.optional(v.string()),
}),
v.object({
kind: v.literal("known_not_billed"),
Expand All @@ -321,7 +329,8 @@ function settlementOutcomesMatch(
(left.kind === "known_not_billed" ||
(right.kind === "known_billed" &&
left.inputTokens === right.inputTokens &&
left.outputTokens === right.outputTokens))
left.outputTokens === right.outputTokens &&
left.servedModel === right.servedModel))
);
}

Expand Down Expand Up @@ -719,7 +728,7 @@ export const reserveChatUsage = internalMutation({
) {
throw new Error("AI chat reservation scope is invalid");
}
const reservedTokens = checkedReservationTokens(
const reservationLimit = checkedReservationTokens(
args.inputTokenLimit,
args.outputTokenLimit,
);
Expand All @@ -737,6 +746,15 @@ export const reserveChatUsage = internalMutation({
)
.first(),
]);
// A reservation keeps the weight it was made with, so a retry after the
// weights change still matches it.
const quotaWeight = existing
? (existing.quotaWeight ?? 1)
: RESERVATION_QUOTA_WEIGHT;
const reservedTokens = reservationLimit * quotaWeight;
if (!Number.isSafeInteger(reservedTokens)) {
throw new Error("AI chat reservation exceeds the supported range");
}
if (existing) {
const sameProvider =
existing.model === args.model &&
Expand Down Expand Up @@ -944,6 +962,7 @@ export const reserveChatUsage = internalMutation({
requirePendingTicketAction: args.requirePendingTicketAction,
ticketActionProposalVersion: action.proposalVersion,
...quota.snapshot,
...(quotaWeight !== 1 ? { quotaWeight } : {}),
reservedTokens,
status: "pending",
expiresAt: now + CHAT_RESERVATION_TTL_MS,
Expand Down Expand Up @@ -1218,6 +1237,7 @@ export const settleStagedChatOutcome = internalMutation({
inputTokens: outcome.inputTokens,
outputTokens: outcome.outputTokens,
model: reservation.model,
...(outcome.servedModel ? { servedModel: outcome.servedModel } : {}),
provider: reservation.provider ?? "google",
reservationKey: reservation.reservationKey,
reservationAttemptToken: reservation.attemptToken,
Expand Down Expand Up @@ -2791,6 +2811,9 @@ export function createMeteredProvider(
inputTokens: result.usage.promptTokens,
outputTokens: result.usage.completionTokens,
providerRequestId,
...(result.servedModelId
? { servedModel: result.servedModelId }
: {}),
};
const resultCheckpointJson = serializeChatResultCheckpoint(
result,
Expand Down
Loading
Loading