Advanced RAG-powered codebase awareness for OpenCode agents. Features Chunk Cards synthesis, hierarchical reasoning, ActiveSet working memory, and performance optimization for enterprise-scale repositories.
npm install opencode-autognosisAdvanced RAG-powered codebase awareness for OpenCode agents. A comprehensive suite of tools that transforms your agent from a file-reader into an "Enterprise Engineer" with deep hierarchical understanding, intelligent working memory management, and production-ready performance optimization.
This plugin relies on the following high-performance system binaries. Please ensure they are installed and in your PATH:
- ripgrep (rg): For fast content searching
- fd (fd): For fast file finding
- ast-grep (sg): For structural code search
- universal-ctags (ctags): For symbol indexing
- git: For version control integration
1. Install the package:
``bash`
npm install opencode-autognosis@latest
2. Configure opencode.json:`
json`
{
"plugin": ["opencode-autognosis"]
}
1. Clone this repository
2. Build the plugin:
`bash`
npm install
npm run build
3. Copy to your project's .opencode/plugins/autognosis.js
The v2.0.0 release is backward compatible with v1.x. All existing tools continue to work unchanged:
`javascript`
// v1.x tools still work exactly the same
autognosis_init({ mode: "apply", token: "..." })
fast_search({ query: "function", mode: "content" })
symbol_query({ symbol: "AuthService" })
jump_to_symbol({ symbol: "AuthService" })
Add the new capabilities to your workflow:
`javascript
// 1. Create Chunk Cards for deep analysis
chunk_create_card({
file_path: "src/auth.ts",
chunk_type: "summary"
})
// 2. Synthesize Module Summaries
module_synthesize({
file_path: "src/auth.ts",
include_reasoning: true
})
// 3. Manage ActiveSet for working memory
activeset_create({
name: "Authentication Module",
chunk_ids: ["auth-summary-abc123"],
context_window: 4000
})
// 4. Optimize performance
perf_incremental_index({
force_full: false,
background: true
})
`
`javascript
// Phase 1: Deep Codebase Understanding
const chunkCards = await Promise.all([
chunk_create_card({ file_path: "src/core.ts", chunk_type: "summary" }),
chunk_create_card({ file_path: "src/core.ts", chunk_type: "api" }),
chunk_create_card({ file_path: "src/core.ts", chunk_type: "invariant" })
]);
// Phase 2: Hierarchical Reasoning
const moduleSummary = module_synthesize({
file_path: "src/core.ts",
include_reasoning: true
});
// Phase 3: Working Memory Management
const activeSet = activeset_create({
name: "Core Module Analysis",
chunk_ids: chunkCards.map(card => card.id),
context_window: 6000,
priority: "high"
});
// Phase 4: Performance Optimization
perf_incremental_index({ background: true });
`
`javascript
// 1. Background indexing for performance
perf_incremental_index({
force_full: false,
parallel_workers: 8,
background: true
});
// 2. Create Chunk Cards for key modules
const keyFiles = ["src/auth.ts", "src/api.ts", "src/database.ts"];
for (const file of keyFiles) {
await chunk_create_card({ file_path: file, chunk_type: "summary" });
await chunk_create_card({ file_path: file, chunk_type: "api" });
}
// 3. Synthesize cross-module understanding
const modules = await Promise.all(
keyFiles.map(file => module_synthesize({ file_path: file }))
);
// 4. Create ActiveSet for focused work
const activeset = activeset_create({
name: "System Architecture",
chunk_ids: modules.flatMap(m => m.chunk_cards.map(c => c.id)),
context_window: 8000
});
`
`javascript
// Monitor performance
const metrics = perf_metrics_get({
operation_filter: "chunk.*",
time_range_hours: 24
});
// Optimize memory if needed
if (metrics.summary.avg_memory_mb > 500) {
perf_optimize_memory({
target_memory_mb: 300,
aggressive: false,
preserve_recent: true
});
}
// Clean up cache
perf_cache_cleanup({
max_age_hours: 12,
max_size_mb: 50,
dry_run: false
});
`
| Tool | Purpose | Key Args |
|------|---------|----------|
| chunk_create_card | Create summary/API/invariant cards | file_path, chunk_type |chunk_get_card
| | Retrieve chunk cards | card_id or file_path |chunk_list_cards
| | List all chunk cards | chunk_type, limit |chunk_delete_card
| | Delete chunk cards | card_id |
| Tool | Purpose | Key Args |
|------|---------|----------|
| activeset_create | Create working memory set | name, chunk_ids, context_window |activeset_load
| | Load existing set | set_id |activeset_add_chunks
| | Add chunks to set | chunk_ids, enforce_capacity |activeset_get_current
| | Get current set status | include_chunks |activeset_list
| | List all sets | priority_filter, limit |
| Tool | Purpose | Key Args |
|------|---------|----------|
| module_synthesize | Create module summary | file_path, include_reasoning |module_get_summary
| | Retrieve module summary | file_path or module_id |module_hierarchical_reasoning
| | Deep reasoning analysis | module_id, reasoning_depth |module_cross_reference
| | Find module relationships | module_id, reference_depth |
| Tool | Purpose | Key Args |
|------|---------|----------|
| perf_incremental_index | Smart re-indexing | force_full, background |perf_cache_get
| /perf_cache_set | Intelligent caching | operation, params, value |perf_metrics_get
| | Performance monitoring | operation_filter, time_range_hours |perf_optimize_memory
| | Memory optimization | target_memory_mb, aggressive |
The plugin includes comprehensive testing tools:
`javascript
// Test all tool contracts
test_run_contract({
tool_filter: "chunk.*",
strict_mode: true
});
// Test multi-agent scenarios
test_integration_parallel({
agent_count: 3,
operation_count: 10,
stress_level: "medium"
});
// Performance benchmarks
test_performance_benchmark({
benchmark_type: "all",
iterations: 100,
data_size: "medium"
});
`
Typical performance improvements over v1.x:
| Operation | v1.x Time | v2.0 Time | Improvement |
|-----------|-----------|-----------|-------------|
| Symbol Query | 150ms | 45ms | 70% faster |
| File Search | 200ms | 60ms | 70% faster |
| Large Repo Index | 45s | 8s | 82% faster |
| Memory Usage | 800MB | 300MB | 62% reduction |
`bashCache configuration
AUTOGNOSIS_CACHE_TTL=3600 # Cache TTL in seconds
AUTOGNOSIS_MAX_CACHE_SIZE=100 # Max cache size in MB
$3
Create
:`json
{
"chunking": {
"default_chunk_type": "summary",
"auto_synthesize": true,
"max_chunk_size": 2000
},
"activeset": {
"default_context_window": 4000,
"max_sets": 10,
"auto_cleanup": true
},
"performance": {
"enable_background": true,
"cache_ttl_seconds": 3600,
"memory_target_mb": 500,
"parallel_workers": 4
},
"indexing": {
"incremental_enabled": true,
"auto_reindex": true,
"file_extensions": [".ts", ".js", ".tsx", ".jsx", ".py", ".go"]
}
}
`🐛 Troubleshooting
$3
Issue: "ctags binary missing"
bash
Solution: Install universal-ctags
brew install universal-ctags # macOS
sudo apt-get install universal-ctags # Ubuntu
`Issue: High memory usage
javascript
// Solution: Optimize memory
perf_optimize_memory({
target_memory_mb: 300,
aggressive: true
});
`Issue: Slow performance on large repos
javascript
// Solution: Enable background indexing
perf_incremental_index({
background: true,
parallel_workers: 8
});
`$3
Enable detailed logging:
javascript
// Check system status
autognosis_init({ mode: "plan" });// Monitor background tasks
perf_background_status({ task_type: "indexing" });
// Check cache health
perf_cache_cleanup({ dry_run: true });
`🤝 Contributing
1. Fork the repository
2. Create feature branch:
3. Build and test: MIT License - see LICENSE file for details.
- Issues: GitHub Issues
- Documentation: Wiki
- Discussions: GitHub Discussions
---
v2.0.0: The most advanced codebase awareness system for OpenCode agents. 🚀