> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ruminate.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a repository

> Analyse your own GitHub repository. Clerk for hosted access, or a token for local development.

Ruminate reads the repository's structure first, then builds the first map of project knowledge. Connecting is the read. Interpretation is a separate step.

## GitHub

Hosted access uses Clerk's GitHub social connection. The connection needs the `repo` scope.

<Steps>
  <Step title="Sign in">
    Create an account or sign in. Then connect GitHub from your account menu if it is not already connected.
  </Step>

  <Step title="Choose a repository">
    Open **New project** from the project switcher and pick a GitHub repository. Ruminate makes a shallow clone (depth 300, single branch) into `.ruminate/repos/`.
  </Step>

  <Step title="Wait for analysis">
    Static analysis maps files, imports, exports, symbols, the client/server boundary, and the dependency graph. That part is facts, not guesses.
  </Step>
</Steps>

Depth 300 rather than 1 because commit history is what turns structural signals from guesses into evidence. The token is passed through a credential helper, so it never lands in `argv` or in `.git/config`.

## Local development

A `GITHUB_TOKEN` in the environment works without the Clerk connection:

```bash theme={null}
GITHUB_TOKEN=$(gh auth token) npm run dev
```

## Build the project brain

Analysis gives you structure. Meaning comes next, in one of two ways:

* **Your coding agent**, through [MCP](/mcp). It reads the real files, then submits systems, technologies, and concepts. Citations that do not resolve are rejected.
* **The hosted pipeline**, which needs `ANTHROPIC_API_KEY`. Two passes run against a structural digest — never the source of the whole repo: technologies and systems, then concepts.

Every line range the model cites is checked against the file it claims to quote. Anything that does not resolve is dropped rather than rendered.

<Note>
  Pointing Ruminate at a local folder on this machine is not available yet.
</Note>