feat: .lightfast repo — org-level context primitive for AI agents

[jeevanpillay]

Summary

Introduce .lightfast — a dedicated GitHub repo ({org}/.lightfast) that serves as the org-level "operating system configuration" for Lightfast. Users create any files/structure they want (markdown, yaml, directories), and AI agents explore it like a codebase via a sandboxed shell.

Motivation

Today there is zero org-level configuration for how Lightfast agents behave. The org name (from Clerk) is the only dynamic element injected into agent prompts. .lightfast would be the first org-level context mechanism — giving orgs a version-controlled, git-native way to define their identity, rules, terminology, and conventions for all AI agents operating on their behalf.

Design

Aspect	Decision
Form	Dedicated GitHub repo: {org}/.lightfast
Content	User-defined — any files/structure (starting with brand.md)
Cardinality	One per org
Onboarding	Lightfast scaffolds it via UI → GitHub App creates the repo
Sync	Push webhooks → re-clone in Vercel Sandbox
MCP exposure	lightfast_shell — sandboxed shell tool against cloned repo
Agents	Both Lightfast platform agents AND user-facing AI tools (Claude Code, Cursor, Codex)

Architecture

User's AI tool (Claude Code, Cursor, Codex)
  → MCP tool: lightfast_shell({ command: "grep -r 'tone' ." })
  → Lightfast API (POST /v1/shell)
  → Vercel Sandbox (pre-cloned .lightfast repo for this org)
  → Execute read-only command in sandbox
  → Return stdout/stderr to agent

Push webhook (on .lightfast repo changes):
  → Lightfast webhook pipeline
  → Re-clone / git pull in sandbox environment

Why Shell Over Structured Endpoints

LLMs already know grep, cat, find, ls, head, tail — no new tool semantics to learn. Users can put any structure in .lightfast without Lightfast needing schema knowledge. One MCP tool covers all use cases.

Example Agent Interactions

# Discover repo contents
lightfast_shell({ command: "find . -name '*.md' -type f" })

# Read a file
lightfast_shell({ command: "cat brand.md" })

# Search across all files
lightfast_shell({ command: "grep -rn 'tone' ." })

# Explore directories
lightfast_shell({ command: "ls -la engineering/" })

Existing Infrastructure (Ready to Build On)

• GitHub App (lightfastai-dev) — already has get-file-contents + list-installation-repos in API catalog
• Webhook pipeline — mature POST /api/ingest/github → Inngest pipeline (needs push event handler)
• MCP server (@lightfastai/mcp) — registerContractTools auto-creates MCP tools from API contract. Adding shell to apiContract automatically registers lightfast_shell — zero MCP code changes
• Prompt engine — section-based architecture in packages/prompt-engine/ for Lightfast's own agents

Implementation Areas

1. API contract + handler: Add POST /v1/shell to apiContract with ShellRequestSchema / ShellResponseSchema
2. Vercel Sandbox integration: Clone .lightfast repo, execute read-only shell commands, return output
3. Webhook handler: Add push event support for .lightfast repos → trigger re-clone/sync
4. Scaffolding UI: "Create .lightfast" button → GitHub App creates repo with starter template
5. GitHub App permissions: May need administration:write scope for repo creation
6. Prompt engine section: New section provider for Lightfast's Answer agent to load .lightfast context
7. Security boundary: Command allowlist, output size limits, org-scoped isolation

Open Questions

• Which Vercel Sandbox product/API to use? (Code Interpreter, serverless function with temp clone, etc.)
• Clone lifecycle — per-request (cold start) or long-lived (needs sync)?
• Command allowlist vs blocklist for security
• Output size limits to prevent blowing up agent context windows
• What goes into the scaffolded .lightfast starter template?
• Should Lightfast's Answer agent also use lightfast_shell, or load key files directly into system prompt?

[coderabbitai]

🔗 Related PRs

#449 - docs: reposition Lightfast as operating infrastructure [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!