Configuration

Dev-agent uses a layered configuration system with sensible defaults.

Configuration File

Run dev init to create a configuration file at .dev-agent/config.json:


{
  "version": "1.0",
  "repository": {
    "path": ".",
    "excludePatterns": [
      "**/node_modules/**",
      "**/dist/**",
      "**/.git/**",
      "**/coverage/**"
    ],
    "languages": ["typescript", "javascript", "markdown"]
  },
  "mcp": {
    "adapters": {
      "search": { "enabled": true },
      "github": { "enabled": true },
      "plan": { "enabled": true },
      "explore": { "enabled": true },
      "status": { "enabled": false }
    }
  }
}

Configuration Options

Repository Settings

Option	Type	Default	Description
`repository.path`	string	`"."`	Path to repository root
`repository.excludePatterns`	string[]	See below	Glob patterns to exclude
`repository.languages`	string[]	`["typescript", "javascript", "markdown"]`	Languages to index

Default Exclude Patterns:

Standard exclusions (all languages):

**/node_modules/** - Dependencies
**/dist/**, **/build/** - Build outputs
**/.git/** - Version control
**/coverage/** - Test coverage reports

TypeScript performance exclusions (configurable):

**/*.mock.ts, **/*.mock.tsx, **/mocks/** - Mock files (no business logic)
**/*.d.ts - Type definition files (verbose, auto-generated)
**/test-utils/**, **/testing/** - Test infrastructure (framework code)

Go-specific exclusions:

**/*.pb.go, **/*.gen.go - Generated code (protobuf, codegen)
**/testdata/** - Test fixtures

MCP Adapter Settings

Control which MCP tools are enabled:

Adapter	Default	Tool	Description
`search`	enabled	`dev_search`	Semantic code search
`github`	enabled	`dev_gh`	GitHub issues/PRs search
`plan`	enabled	`dev_plan`	Context assembly for issues
`inspect`	enabled	`dev_inspect`	File analysis
`status`	disabled	`dev_status`	Repository status
`refs`	enabled	`dev_refs`	Relationship queries
`map`	enabled	`dev_map`	Codebase overview

Disable an adapter:


{
  "mcp": {
    "adapters": {
      "github": { "enabled": false }
    }
  }
}

Environment Variables

Configuration values can reference environment variables using ${VAR_NAME} syntax:


{
  "repository": {
    "path": "${REPO_PATH}"
  }
}

Built-in Environment Variables:

Variable	Description	Used By
`WORKSPACE_FOLDER_PATHS`	Cursor workspace paths	MCP server
`REPOSITORY_PATH`	Explicit repository path	MCP server

Performance Tuning

Control scanning and indexing performance using environment variables:

Variable	Description	Default	Recommended Range
`DEV_AGENT_CONCURRENCY`	Global concurrency setting (applies to all operations)	Auto-detected	5-30
`DEV_AGENT_TYPESCRIPT_CONCURRENCY`	TypeScript file processing concurrency	Auto-detected	5-40
`DEV_AGENT_INDEXER_CONCURRENCY`	Vector embedding batch concurrency	Auto-detected	2-10
`DEV_AGENT_GO_CONCURRENCY`	Go file processing concurrency	Auto-detected	5-30

Auto-detection: If no environment variables are set, dev-agent automatically detects optimal concurrency based on your system’s CPU and memory.

Performance Recommendations

System Type	Global	TypeScript	Indexer	Notes
Low memory (under 4GB)	5	5	2	Prevents OOM errors
Standard (4-8GB)	15	15	3	Balanced performance
High-end (8GB+, 8+ cores)	30	30	5	Maximum speed

Usage Examples

High-performance settings:


export DEV_AGENT_TYPESCRIPT_CONCURRENCY=30
export DEV_AGENT_INDEXER_CONCURRENCY=8
dev index .

Memory-conservative settings:


export DEV_AGENT_CONCURRENCY=5
export DEV_AGENT_INDEXER_CONCURRENCY=2
dev index .

Storage Locations

Dev-agent stores index data in ~/.dev-agent/indexes/:


~/.dev-agent/
└── indexes/
    └── {hash}/           # Per-repository storage
        ├── vectors.lance  # Vector embeddings
        ├── metadata.json  # Repository metadata
        ├── indexer-state.json
        └── github-state.json

Storage path resolution:

If repository has a git remote → hash of owner/repo
Otherwise → hash of absolute path

This means the same repository cloned to different locations shares the same index.

Check Storage Location


dev storage path
# Output: ~/.dev-agent/indexes/a1b2c3d4/
 
dev storage size
# Output: 12.5 MB

Cursor Integration

Cursor uses a global MCP config at ~/.cursor/mcp.json:


{
  "mcpServers": {
    "dev-agent": {
      "command": "dev",
      "args": ["mcp", "start"]
    }
  }
}

Automatic workspace detection:

Cursor sets WORKSPACE_FOLDER_PATHS automatically
Single config works across all projects
No per-project configuration needed

Install with:


dev mcp install --cursor

Claude Code Integration

Claude Code uses the claude CLI for MCP configuration:


# Install
dev mcp install
 
# List servers
claude mcp list
 
# Remove
dev mcp uninstall

Embedding Model

Dev-agent uses Xenova/all-MiniLM-L6-v2 for embeddings:

Property	Value
Model	all-MiniLM-L6-v2
Dimensions	384
Provider	@xenova/transformers
Location	Local (no API calls)

The model is downloaded on first run (~23MB) and cached locally.

Advanced: Custom Exclude Patterns

Default Patterns

Running dev init creates a config with these default exclusions:


{
  "repository": {
    "excludePatterns": [
      // Standard exclusions
      "**/node_modules/**", "**/dist/**", "**/.git/**", "**/coverage/**",
      // TypeScript performance exclusions
      "**/*.mock.ts", "**/*.mock.tsx", "**/mocks/**",
      "**/*.d.ts", "**/test-utils/**", "**/testing/**"
    ]
  }
}

Customization Options

Add project-specific patterns:


{
  "repository": {
    "excludePatterns": [
      "**/node_modules/**", "**/dist/**", "**/.git/**", "**/coverage/**",
      "**/*.mock.ts", "**/*.mock.tsx", "**/mocks/**", "**/*.d.ts",
      "**/test-utils/**", "**/testing/**",
      // Your custom patterns
      "**/vendor/**", "**/*.generated.ts", "**/legacy/**"
    ]
  }
}

Include TypeScript definition files (if desired):


{
  "repository": {
    "excludePatterns": [
      "**/node_modules/**", "**/dist/**", "**/.git/**", "**/coverage/**",
      "**/*.mock.ts", "**/*.mock.tsx", "**/mocks/**",
      "**/test-utils/**", "**/testing/**"
      // Removed "**/*.d.ts" to include type definitions in search
    ]
  }
}

Troubleshooting

Config Not Found


# Check if config exists
ls -la .dev-agent/config.json
 
# Create config
dev init

Environment Variable Not Set

If you see Environment variable X is not set:


# Set the variable
export REPO_PATH=/path/to/repo
 
# Or use a literal value in config instead

Storage Permission Issues


# Check permissions
ls -la ~/.dev-agent/
 
# Fix permissions
chmod -R 755 ~/.dev-agent/