The Problem

Building an AI agent that answers questions from a live knowledge base usually means standing up an embedding pipeline, a vector database, and a chunking service. That is infrastructure to operate and drift to manage. This template removes that layer entirely: the agent searches source files directly with grep, find, and cat inside isolated sandboxes.

What This Does

The repo is a fork of vercel-labs/knowledge-agent-template. It provides a full application—Nuxt frontend, Nitro server, and an agent package—that connects to GitHub repos, YouTube transcripts, or custom APIs. A user asks a question in a chat UI, a GitHub Issue, or Discord; the agent classifies question complexity, routes to an appropriate model, and searches the sandboxed file system for answers.

The template also ships an admin panel (apps/app/app/pages/admin/) with usage stats, logs, and user management, plus an AI admin agent that answers operational questions via internal tools like query_stats and run_sql.

How It Is Wired

Execution starts in apps/app/server/utils/bot/index.ts and routes through apps/app/server/utils/chat/admin-tools/index.ts. The agent core lives in packages/agent/src/; packages/agent/src/router/schema.ts classifies incoming questions and dispatches to models, and packages/agent/src/core/context.ts manages the agent's execution context.

The most heavily depended-upon modules are apps/app/server/utils/sandbox/types and apps/app/server/workflows/sync-docs/types (11 importers each), but the highest blast radius sits in packages/agent/src/agents/source (instability 0.92) and packages/agent/src/index (instability 1.0) — both are leaf modules that import many things, so changes there ripple outward. The sandbox system (apps/app/server/utils/sandbox/) owns the file-system effects: snapshot-config.ts and snapshot.ts manage pooled sandboxes and pre-built snapshots.

A run does the following: a chat message hits apps/app/server/api/chats/[id].post.ts, which calls the bot utility, which invokes the agent. The agent runs shell commands inside a sandbox via apps/app/server/api/sandbox/shell.post.ts. The whole path is about four hops from HTTP request to filesystem command.

How To Use It

The repo is a template; the README points to a Vercel deploy button. Local setup is inferred from package.json and apps/app/package.json (npm/pnpm workspace):

git clone https://github.com/moses-y/knowledge-agent-template
cd knowledge-agent-template
npm install

Required environment variables live in apps/app/.env.example: BETTER_AUTH_SECRET, GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET. Run the app with npm run dev from the root (inferred from the workspace setup). Database migrations exist in apps/app/server/db/migrations/postgresql/.

Real-World Use

A team with a private GitHub repo of internal docs and runbooks deploys this as a Discord bot. An engineer asks "What's the deploy process for the billing service?" The agent greps the repo, finds the relevant runbook, and answers with a source citation. No vector DB to maintain, no embeddings to regenerate when docs change.

Code Health & Issues

Static analysis (not opinion) found 11 issues: 1 high, 10 medium.

  • High - duplicated code blocks - 222 repeated 6-line blocks across 52 files, including apps/app/app/app.vue, apps/app/app/pages/login.vue, and apps/app/app/components/SourceCard.vue. Extract shared helpers.
  • Medium - high branching density - packages/agent/src/router/schema.ts has 19 branch points over 56 lines; also packages/agent/src/core/context.ts and apps/app/shared/utils/tools/chart.ts. Consider table-driven dispatch.
  • Medium - deep nesting - apps/app/app/layouts/default.vue and apps/app/app/pages/admin/stats.vue hit indentation depth 6.
  • Medium - oversized file - apps/app/app/pages/admin/new.vue is 636 lines.

SDLC observations: 1 test file against 200 source files (ratio 0.005). CI exists (GitHub Actions) but no dependency vulnerability scan. No lockfile committed, so builds are non-reproducible. GitHub Actions are pinned to tags (oven-sh/setup-bun@v2), not commit SHAs — a supply-chain risk.

The Bottom Line

The core idea — no embeddings, search files directly — is sound and removes real operational overhead. The codebase is a working template with a complete UI and multi-platform bots. It needs test coverage and CI hardening before production use, and the duplicated logic across the Vue components will make maintenance tedious. Good starting point for a team that wants a file-search agent without standing up a vector stack.