How to Connect Your First Repo with Tendril

Prerequisites

You'll need:

• A Tendril account (Free or Pro — both support repo connection)
• A GitHub account with at least read access to the repo you want to connect
• The repo pushed to GitHub (private repos are fully supported)

No CLI tools or local environment setup is required at this stage. Tendril works entirely from the GitHub API during ingestion.

GitHub OAuth Flow

When you click Connect Repository in the Tendril dashboard, you'll be redirected to GitHub's OAuth authorization screen. Tendril requests the following scopes:

• repo — read-only access to your code, file tree, and metadata
• read:user — resolves your GitHub identity to your Tendril workspace

What Tendril does NOT request

Tendril never requests write access during authorization. Agent-driven commits happen through a separate, review-gated pull request flow — not through the initial OAuth token. Your code stays on GitHub's infrastructure; Tendril only reads what it needs to build context.

After approving, GitHub redirects you back to Tendril with an authorization code. Tendril exchanges this for an access token and stores it encrypted in your workspace (AES-256, never logged).

What Tendril Scans

Once connected, Tendril's ingestion pipeline walks your repository in three passes:

Pass 1 — Manifest & Config Files

Tendril reads every manifest and config file it recognizes to identify your stack, dependencies, and tooling. Files scanned include:

• package.json / package-lock.json — Node.js dependencies and scripts
• tsconfig.json / tsconfig.*.json — TypeScript compiler settings and path aliases
• pyproject.toml, requirements.txt, Pipfile — Python environments
• go.mod, Cargo.toml, pom.xml — Go, Rust, Java roots
• .env.example — environment variable surface (never .env itself)
• astro.config.*, vite.config.*, webpack.config.* — build tooling

Pass 2 — File Tree Structure

Tendril maps every directory and file path into a tree representation. This gives the main AI agent spatial awareness of your project — it knows where feature code lives versus test files versus infrastructure definitions without having to read every file on every run.

Pass 3 — Entry Points & Key Modules

Tendril samples entry points (src/index.*, main.*, app.*, route directories) to understand public API surfaces and module boundaries. It does not read every source file — it builds a structural model, not a verbatim copy.

What the Project Context Summary Looks Like

After ingestion completes, the main AI agent generates a Project Context Summary — a structured JSON document it prepends to every agent run. This is what gives agents memory that persists across sessions.

{
  "project": "tendril-website",
  "stack": ["Astro 4.16", "React 19", "TypeScript 5.7", "Tailwind 3.4"],
  "runtime": "Node 20 (static output)",
  "entryPoints": ["src/pages/index.astro", "src/layouts/Layout.astro"],
  "keyDependencies": {
    "framer-motion": "12.38.0",
    "three": "0.183.2",
    "@astrojs/react": "4.2.0"
  },
  "buildCommand": "npm run build",
  "outputDir": "dist/",
  "pathAliases": { "@components": "src/components", "@layouts": "src/layouts" },
  "fileCount": 54,
  "testFramework": null,
  "notes": "Static site. No backend. Email capture is frontend stub only."
}

The agent uses this context to make informed decisions — for example, knowing it should use Tailwind utilities instead of custom CSS, or that it shouldn't generate server-side API routes because the project is static output.

Verify Ingestion Completed

You'll know ingestion is done when:

• The repository card in your dashboard shows a green Context Ready badge
• The Project Context panel is populated with your stack, file count, and key modules
• The Run Agent button becomes active (it's disabled during ingestion)

Troubleshooting Incomplete Ingestion

If ingestion stalls after 60 seconds, the most common causes are:

• Repos larger than 500MB — Tendril scans the structure, not file contents, but very large binary assets can slow tree traversal
• GitHub API rate limits — if you've connected several repos in quick succession, wait a few minutes and retry
• Missing package.json in a Node.js project — add one at the repo root to help Tendril identify your stack correctly

Next Steps

With your repo connected and context verified, you're ready to run your first agent task:

• Run Parallel Agents → — break a task into steps and run multiple agents at the same time (Pro)
• Use the Knowledge Graph → — understand how context accumulates across runs over time