Repository Navigation for AI Agents

This guide explains how AI agents can efficiently navigate the VoiceAssist repository using machine-readable JSON endpoints.

Endpoints Overview

Path Encoding

File paths are encoded for URL safety:

• Forward slashes (/) become double underscores (__)
• .json extension is appended

Examples:

Component Categories

Files are categorized by their location in the monorepo:

Navigation Patterns

Pattern 1: Top-Down Discovery

Start with the manifest to understand project structure:

# 1. Get overview stats
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '{
  files: .stats.total_files,
  dirs: .stats.total_dirs,
  size_mb: (.stats.total_size_bytes / 1048576 | floor),
  languages: .stats.by_language,
  components: .stats.by_component
}'

# 2. List key entry points from manifest
curl https://assistdocs.asimo.io/agent/repo/manifest.json | jq '[.files[] | select(.path | endswith("main.py") or endswith("page.tsx"))]'

Pattern 2: Component-Focused Search

When working on a specific component:

# Find all files in web-app
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.component == "frontend/web-app" and .type == "file")]'

# Find React components
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.component == "frontend/web-app" and (.path | test("components/")))]'

Pattern 3: Keyword Search

Find files by name pattern:

# Find files with "voice" in path
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.path | test("voice"; "i"))]'

# Find hook files
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.path | test("use[A-Z].*\\.ts"))]'

Pattern 4: Language-Based Exploration

When understanding technology stack:

# All TypeScript files
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.language == "typescript")] | length'

# All Python files in backend
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.language == "python" and (.component | startswith("backend")))]'

Pattern 5: File Content Retrieval

Fetch and analyze source code:

# Get file content
curl https://assistdocs.asimo.io/agent/repo/files/services__api-gateway__app__main.py.json | jq '{
  path: .path,
  language: .language,
  lines: .lines,
  content: .content
}'

# Check for specific imports (using content)
curl https://assistdocs.asimo.io/agent/repo/files/services__api-gateway__app__main.py.json | jq '.content' | grep -i "from fastapi"

Workflow: Locate a Feature

Goal: Find implementation of "voice mode" feature

# Step 1: Find voice-related docs
curl https://assistdocs.asimo.io/agent/docs.json | jq '[.docs[] | select(.path | test("voice"; "i"))] | map({title, path, ai_summary})'

# Step 2: Find voice-related code files
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.type == "file" and (.path | test("voice"; "i")))] | map({path, component, language})'

# Step 3: Categorize by component
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.type == "file" and (.path | test("voice"; "i")))] | group_by(.component) | map({component: .[0].component, count: length})'

# Step 4: Get key implementation file
curl https://assistdocs.asimo.io/agent/repo/files/services__api-gateway__app__api__voice.py.json

Workflow: Audit Docs vs Code

Goal: Verify documented API endpoints exist in code

# Step 1: Get documented API endpoints
curl https://assistdocs.asimo.io/agent/docs.json | jq '[.docs[] | select(.path | test("API_REFERENCE"))]'

# Step 2: Find API route handlers
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.path | test("services/api-gateway/app/api/.*\\.py$"))]'

# Step 3: Compare documented vs implemented routes
# (Fetch each file and extract route decorators)

Workflow: Understand Package Dependencies

# Step 1: Get all package.json files
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.path | endswith("package.json"))]'

# Step 2: Fetch root package.json
curl https://assistdocs.asimo.io/agent/repo/files/package.json.json | jq '.content | fromjson | {dependencies, devDependencies}'

# Step 3: Check pnpm workspace config
curl https://assistdocs.asimo.io/agent/repo/files/pnpm-workspace.yaml.json

Best Practices

Efficiency

1. Start with manifest for common files (faster, smaller payload)
2. Use repo-index only when searching across entire codebase
3. Cache responses - repo structure doesn't change frequently
4. Filter server-side using jq before processing

Accuracy

1. Verify paths exist before fetching file content
2. Check last_modified to ensure you have current data
3. Cross-reference docs when interpreting code

Limitations

• File size limit: Files over 100KB are not exported (error returned)
• Excluded patterns: .env, secrets, test files, lock files
• Binary files: Only text files are included
• Update frequency: Regenerated on docs-site build

Related Documentation

• Agent API Reference - Complete endpoint documentation
• Agent Task Index - Common agent tasks
• Agent Onboarding - Getting started guide