admin/SuperCharged-Claude-Code-Upgrade
1
2
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: admin:3b128ba3bdc41e26e8be8b8a4a7f7486c4103ab5
Branches Tags
admin:main admin:master
...
compare: admin:87748afb75d62858284f6ee4a3b2e645a254fafa
Branches Tags
admin:main admin:master

2 Commits
3b128ba3bd ... 87748afb75

  • feat: Complete sync of all Claude Code CLI upgrades 
    - Add all 21 commands (clawd, ralph, prometheus*, dexto*)
- Add all hooks (intelligent-router, clawd-*, prometheus-wrapper, unified-integration-v2)
- Add skills (ralph, prometheus master)
- Add MCP servers (registry.json, manager.sh)
- Add plugins directory with marketplaces
- Add health-check.sh and aliases.sh scripts
- Complete repository synchronization with local ~/.claude/

Total changes: 100+ new files added
All integrations now fully backed up in repository

🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
    uroma · 2026-01-27 20:39:25 +00:00
    87748afb75
  • feat: Add intelligent auto-router and enhanced integrations 
    - Add intelligent-router.sh hook for automatic agent routing
- Add AUTO-TRIGGER-SUMMARY.md documentation
- Add FINAL-INTEGRATION-SUMMARY.md documentation
- Complete Prometheus integration (6 commands + 4 tools)
- Complete Dexto integration (12 commands + 5 tools)
- Enhanced Ralph with access to all agents
- Fix /clawd command (removed disable-model-invocation)
- Update hooks.json to v5 with intelligent routing
- 291 total skills now available
- All 21 commands with automatic routing

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
    admin · 2026-01-28 00:27:56 +04:00
    b52318eeae
1904 changed files with 366057 additions and 3 deletions
Expand all files Collapse all files

216
AUTO-TRIGGER-SUMMARY.md Normal file
View File

@@ -0,0 +1,216 @@
# Auto-Trigger Integration Complete ✅
**Date:** 2026-01-27
**Status:** ✅ All agents auto-routing enabled via Ralph
---
## What Was Added
### 1. Intelligent Router Hook
**File:** `~/.claude/hooks/intelligent-router.sh`
This hook automatically analyzes user prompts and suggests the best agent for the task. It runs on every `UserPromptSubmit` event.
**Routing Logic:**
- Analyzes task keywords and patterns
- Calculates confidence scores (threshold: 70%)
- Suggests appropriate agent command
- Covers ALL 21 integrated commands
### 2. Enhanced Ralph Command
**File:** `~/.claude/commands/ralph.md` (updated)
Ralph now:
- Has access to ALL integrated agents (Clawd, Prometheus, Dexto)
- Routes to best agent automatically
- Can orchestrate multi-agent workflows
- Removed `disable-model-invocation` for proper functionality
### 3. Enhanced Ralph Skill
**File:** `~/.claude/skills/ralph/enhanced-ralph.md` (new)
Complete documentation of all agents and routing patterns.
### 4. Updated Hooks Configuration
**File:** `~/.claude/hooks.json` (updated to v5)
Added `intelligent-router.sh` as the first hook in UserPromptSubmit chain.
---
## Auto-Routing Patterns
| Task Pattern | Routes To | Example |
|-------------|-----------|---------|
| "autonomous", "automatically", "on its own" | `/clawd` | "Handle this autonomously" |
| "architecture", "design system", "from scratch" | `/ralph` | "Design microservices architecture" |
| "bug", "fix", "reproduce", "regression" | `/prometheus-bug` | "Fix authentication bug" |
| "feature", "implement", "add functionality" | `/prometheus-feature` | "Add two-factor auth" |
| "code context", "how does", "explain" | `/prometheus-context` | "How does payment work?" |
| "github", "pr", "issue", "commit" | `/dexto-github` | "Analyze the pull request" |
| "pdf", "document", "summarize paper" | `/dexto-pdf` | "Summarize this document" |
| "generate image", "create picture", "ai art" | `/dexto-nano-banana` | "Generate an image" |
| "video", "sora", "generate clip" | `/dexto-sora` | "Create a video" |
| "music", "audio", "podcast", "beat" | `/dexto-music` | "Create a beat" |
| "database", "sql", "query", "schema" | `/dexto-database` | "Optimize this query" |
| "explore code", "analyze codebase" | `/dexto-explore` | "Explore this codebase" |
| "product name", "branding", "research" | `/dexto-research` | "Research product names" |
| "support ticket", "triage", "categorize" | `/dexto-triage` | "Triage this ticket" |
---
## How It Works
### User Experience
1. **User types a task:**
```
Fix the authentication bug in the login system
```
2. **Intelligent Router analyzes:**
- Detects "bug", "fix", "authentication" keywords
- Matches to Prometheus Bug Analyzer (score: 85)
- Confidence: high
3. **Suggestion appears:**
```
💡 **Tip:** This is a code analysis task. Use Prometheus: `/prometheus "Fix the authentication bug in the login system"`
```
4. **User can:**
- Click/tap the suggested command
- Type it manually
- Ignore and use default Claude
- Use `/ralph` to let Ralph orchestrate
### Ralph Orchestration
When using `/ralph`, it:
1. Analyzes task requirements
2. Selects best agent automatically
3. For complex tasks, chains multiple agents:
- Example: "Analyze code, find bugs, create fix plan"
- Ralph chains: `dexto-explore` → `prometheus-bug` → `prometheus-feature`
---
## Examples
### Example 1: Bug Fix
```
User: "The login is broken after password reset"
Router detects: bug pattern
Suggestion: 💡 Use Prometheus: `/prometheus-bug "The login is broken after password reset"`
```
### Example 2: Image Generation
```
User: "Create an image of a cyberpunk city"
Router detects: image generation pattern
Suggestion: 💡 Use Dexto nano-banana agent: `/dexto-nano-banana "Create an image of a cyberpunk city"`
```
### Example 3: Architecture Design
```
User: "Design a scalable e-commerce backend"
Router detects: architecture pattern
Suggestion: 💡 This is a complex architecture task. Ralph can help: `/ralph "Design a scalable e-commerce backend"`
```
### Example 4: Autonomous Execution
```
User: "Automatically deploy the application to production"
Router detects: autonomous pattern
Suggestion: 💡 This task looks suitable for autonomous execution. Consider using: `/clawd "Automatically deploy the application to production"`
```
---
## Configuration
### Enable/Disable Router
Edit `~/.claude/hooks.json`:
```json
{
"type": "command",
"command": "/home/roman/.claude/hooks/intelligent-router.sh",
"timeout": 10
}
```
### Adjust Confidence Threshold
Edit `~/.claude/hooks/intelligent-router.sh`:
```bash
if [ "$SCORE" -ge 70 ]; then # Change 70 to desired threshold
```
### Add New Patterns
Add to the detect patterns in `intelligent-router.sh`:
```bash
if echo "$prompt" | grep -qiE "(your|pattern)"; then
best_agent="your-agent"
best_score=80
fi
```
---
## Testing
Test the router:
```bash
# Test various patterns
echo "Fix this bug" | ~/.claude/hooks/intelligent-router.sh
echo "Generate an image" | ~/.claude/hooks/intelligent-router.sh
echo "Design architecture" | ~/.claude/hooks/intelligent-router.sh
echo "Handle this autonomously" | ~/.claude/hooks/intelligent-router.sh
```
---
## Files Modified/Created
```
~/.claude/
├── hooks/
│ ├── intelligent-router.sh # NEW - Auto-routing logic
│ └── hooks.json # UPDATED - v5 with router
├── commands/
│ └── ralph.md # UPDATED - Enhanced capabilities
└── skills/
└── ralph/
└── enhanced-ralph.md # NEW - Documentation
```
---
## Health Check
```bash
~/.claude/health-check.sh
```
**Status:** ✅ All systems operational (291 skills)
---
## Summary
Your Claude Code CLI now has **intelligent auto-routing** that:
1. ✅ **Detects task type** from natural language
2. ✅ **Suggests best agent** automatically
3. ✅ **Routes via Ralph** for complex orchestration
4. ✅ **Covers all 21 commands** (Clawd, Prometheus, Dexto)
5. ✅ **Runs on every prompt** via hooks
**Just describe your task and the system will guide you to the best tool! 🎯**

1
ClaudeCLI-Web Submodule

Submodule ClaudeCLI-Web added at db862600bd

257
FINAL-INTEGRATION-SUMMARY.md Normal file
View File

@@ -0,0 +1,257 @@
# Claude Code CLI - Complete Production Integration Summary
**Date:** 2026-01-27
**Status:** ✅ ALL SYSTEMS OPERATIONAL
---
## 🎉 Overview
Your Claude Code CLI now has comprehensive production-grade integrations with multiple AI agent frameworks, tools, and systems. All components are fully operational and ready for use.
---
## 📊 Integrated Systems
### 1. Clawd ✅
- **Source:** Internal/custom setup
- **Type:** Autonomous task execution gateway
- **Status:** Running (PID: 23762, Port: 8766)
- **Command:** `/clawd "task"`
- **Capability:** Multi-agent task delegation with persistent sessions
### 2. Ralph ✅
- **Source:** Ralph Orchestrator
- **Type:** "Tackle Until Solved" autonomous iteration
- **Status:** Binary installed and symlinked
- **Command:** `/ralph "complex task"`
- **Capability:** Architecture design, multi-step implementations
### 3. Prometheus (EuniAI) ✅
- **Source:** https://github.com/EuniAI/Prometheus
- **Type:** Multi-agent code analysis system
- **Status:** Integrated (6 commands + 4 tools + master)
- **Commands:** `/prometheus-bug`, `/prometheus-feature`, etc.
- **Capability:** Bug fixing, feature implementation, code analysis
### 4. Dexto (Truffle AI) ✅
- **Source:** https://github.com/truffle-ai/dexto
- **Type:** Multi-agent framework
- **Status:** Integrated (12 commands + 5 tools + master)
- **Commands:** `/dexto-code`, `/dexto-github`, `/dexto-pdf`, etc.
- **Capability:** Development, media creation, databases, GitHub
---
## 📁 Complete Command List
### Clawd (1 command)
```
/clawd "Your task"
```
### Ralph (1 command)
```
/ralph "Your complex task"
```
### Prometheus (7 commands)
```
/prometheus-classify "issue" # Classify issue type
/prometheus-bug "bug report" # Analyze and fix bugs
/prometheus-feature "request" # Plan features
/prometheus-context "query" # Get code context
/prometheus-edit "change" # Generate edits
/prometheus-test "test suite" # Run tests
/prometheus "any task" # Auto-select agent
```
### Dexto (12 commands)
```
/dexto-code "task" # Development
/dexto-database "query" # Database operations
/dexto-github "repo/issue/pr" # GitHub operations
/dexto-pdf "document" # PDF analysis
/dexto-image-edit "image" # Image editing
/dexto-nano-banana "prompt" # AI images (Gemini 2.5)
/dexto-sora "prompt" # Video generation (Sora)
/dexto-music "idea" # Music creation
/dexto-podcast "topic" # Podcast generation
/dexto-research "product" # Product research
/dexto-triage "ticket" # Support triage
/dexto-explore "codebase" # Code exploration
```
---
## 🛠️ Tool Skills
### Prometheus Tools (4)
- **File Operations** - AST-based code parsing
- **Graph Traversal** - Knowledge graph navigation
- **Container** - Docker execution
- **Web Search** - Documentation lookup
### Dexto Tools (5)
- **Filesystem** - Advanced file operations
- **Playwright** - Browser automation
- **Process** - System commands
- **TODO** - Task management
- **Plan** - Project planning
### MCP Servers (10 registered)
- **arc** - Subagent file operations
- **claude-mem** - Persistent memory
- **filesystem** - Local filesystem
- **git** - Git operations
- **fetch** - HTTP requests
- **sqlite** - Database
- And more...
---
## 📈 Statistics
| Component | Count |
|-----------|-------|
| **Total Commands** | 21 |
| **Agent Frameworks** | 4 |
| **Tool Skills** | 9 |
| **MCP Servers** | 10 |
| **Total Skills** | 295 |
| **Plugins** | 2 |
| **Hooks** | 5 |
---
## 🚀 Quick Start Examples
### Development Tasks
```bash
# Fix a bug
/clawd "Fix the authentication bug"
/prometheus-bug "Login fails after password reset"
/dexto-code "Review the pull request"
# Implement a feature
/prometheus-feature "Add two-factor authentication"
/ralph "Design a microservices architecture for e-commerce"
# Analyze code
/dexto-explore "Analyze this codebase structure"
/prometheus-context "How does payment processing work?"
```
### Media & Content
```bash
# Generate images
/dexto-nano-banana "A futuristic city at sunset"
/dexto-image-edit "Resize and enhance this photo"
# Create video
/dexto-sora "A robot learning to paint"
# Audio content
/dexto-music "Create a lo-fi beat for studying"
/dexto-podcast "Generate a podcast about AI safety"
# Documents
/dexto-pdf "Summarize this research paper"
```
### Operations
```bash
# GitHub
/dexto-github "Analyze issues in the repository"
# Database
/dexto-database "Optimize this slow query"
# Research
/dexto-research "Find a name for my productivity app"
/prometheus-classify "Categorize this customer feedback"
```
---
## 🔧 Configuration Files
```
~/.claude/
├── settings.json # Main settings
├── hooks.json # Hook configuration
├── config.json # Config
├── health-check.sh # Health monitoring
├── aliases.sh # Command aliases
│
├── clawd/ # Clawd gateway
│ └── gateway.pid # Running process
├── ralph-integration/ # Ralph integration
├── prometheus/ # Prometheus integration
│ └── integrate-all.sh # Integration script
├── dexto/ # Dexto integration
│ └── integrate-all.sh # Integration script
└── mcp-servers/ # MCP infrastructure
├── registry.json # Server definitions
└── manager.sh # Start/stop/status
```
---
## 🩺 Health Monitoring
Run the health check anytime:
```bash
~/.claude/health-check.sh
```
Current status: **✅ ALL SYSTEMS OPERATIONAL**
---
## 📝 Master Skills
For automatic agent/tool selection, use the master skills:
- **prometheus-master** - Automatically selects Prometheus components
- **dexto-master** - Automatically selects Dexto agents
Usage:
```
"Use prometheus to analyze this bug"
"Use dexto to generate an image"
```
---
## 🎯 Next Steps
All integrations are complete and operational!
For advanced usage:
1. Configure API keys (OpenAI, Gemini, etc.) in respective configs
2. Set up Neo4j for Prometheus knowledge graph (optional)
3. Configure GitHub tokens for Dexto GitHub agent
4. Customize agent configurations in `~/.claude/*/agents/`
---
## 📚 Documentation
- **Clawd:** `~/.claude/clawd/docs/`
- **Prometheus:** `~/.claude/prometheus/README.md`
- **Dexto:** `~/.claude/dexto/README.md`
- **Integration:** `~/.claude/UPGRADE-SUMMARY.md`
---
**🎉 Your Claude Code CLI is now a comprehensive multi-agent AI platform! 🎉**
Total capabilities:
- ✅ Autonomous task execution (Clawd)
- ✅ Architecture design (Ralph)
- ✅ Code analysis (Prometheus)
- ✅ Multi-agent framework (Dexto)
- ✅ 295 specialized skills
- ✅ 10 MCP servers
- ✅ Production-grade monitoring

50
aliases.sh Executable file
View File

@@ -0,0 +1,50 @@
#!/bin/bash
# Claude Code Production-Grade Aliases v2
# Source this file in your .bashrc: source ~/.claude/aliases.sh
# Core binaries
alias ralph-loop='~/.claude/skills/bin/ralphloop'
alias ralphloop='~/.claude/skills/bin/ralphloop'
# Health and management
alias claude-health='~/.claude/health-check.sh'
alias health-check='~/.claude/health-check.sh'
alias mcp-status='~/.claude/mcp-servers/manager.sh status'
alias mcp-start='~/.claude/mcp-servers/manager.sh start'
alias mcp-stop='~/.claude/mcp-servers/manager.sh stop'
alias mcp-restart='~/.claude/mcp-servers/manager.sh restart'
# Clawd
alias clawd-status='curl -s http://127.0.0.1:8766/health | jq .'
alias clawd-logs='tail -f ~/.claude/clawd/logs/gateway.log'
# Prometheus
alias prometheus-install='bash ~/.claude/prometheus/install.sh'
alias prometheus-status='ls -la ~/.claude/prometheus/venv && echo "Prometheus installed" || echo "Prometheus not installed"'
alias prometheus-logs='tail -f ~/.claude/prometheus/logs/prometheus.log'
alias prometheus-task='~/.claude/hooks/prometheus-wrapper.sh'
# Quick commands
alias clawd-task='~/.claude/hooks/clawd-wrapper.sh --task'
alias ralph-task='~/.claude/skills/bin/ralphloop'
# Info
alias claude-info='echo "Claude Code CLI - Production Grade" && ~/.claude/health-check.sh | grep -E "✓|✗|⚠"'
alias claude-plugins='jq -r ".plugins | keys[]" ~/.claude/plugins/installed_plugins.json'
alias claude-skills='find ~/.claude/skills -maxdepth 1 -type d | wc -l && echo "skills available"'
# Documentation
alias claude-upgrade-summary='cat ~/.claude/UPGRADE-SUMMARY.md'
alias prometheus-docs='cat ~/.claude/PROMETHEUS-INTEGRATION.md'
# Development
alias mcp-edit='${EDITOR:-nano} ~/.claude/mcp-servers/registry.json'
alias hooks-edit='${EDITOR:-nano} ~/.claude/hooks.json'
alias settings-edit='${EDITOR:-nano} ~/.claude/settings.json'
# Logs
alias claude-logs='tail -f ~/.claude/logs/health-check.log'
alias mcp-logs='tail -f ~/.claude/mcp-servers/logs/*.log'
echo "Claude Code aliases loaded (v2 with Prometheus)."
echo "Type 'claude-info' for status, 'prometheus-docs' for Prometheus info."

6
commands/auto-loop.md Normal file
View File

@@ -0,0 +1,6 @@
---
description: "Autonomous Loop 'Tackle Until Solved' - Self-referential iteration agent for complex multi-step tasks. Persists work between iterations until completion criteria met."
disable-model-invocation: true
---
Invoke the superpowers:autonomous-loop skill and follow it exactly as presented to you

6
commands/autonomous-plan.md Normal file
View File

@@ -0,0 +1,6 @@
---
description: "Autonomous task decomposition and action planning for complex software development workflows. Breaks complex requests into actionable steps with automatic tool/model selection and quality gates."
disable-model-invocation: true
---
Invoke the superpowers:autonomous-planning skill and follow it exactly as presented to you

21
commands/call-openrouter.md Executable file
View File

@@ -0,0 +1,21 @@
# Multi-Model Collaboration Strategy
## Objective
Your goal is to produce a high-quality, robust solution to the user's request by orchestrating collaboration between specialist AI models.
## Core Strategy
Follow this flexible, three-stage approach:
1. **Propose:** Use a strong, general-purpose model to analyze the user's request and generate a comprehensive initial plan or solution.
2. **Critique & Refine:** Use a different, highly capable model to act as a "red teamer." This model's task is to critique the initial plan, identify potential edge cases, find security vulnerabilities, check for alignment with the user's true intent, and suggest alternative approaches.
3. **Synthesize & Implement:** Based on the critique, synthesize the feedback into a final, superior plan. Once the plan is solidified, implement the necessary code changes.
## Guiding Principles
- **Context is King:** Your most critical task is to provide maximum relevant file context to all models. The quality of their output depends entirely on this. Before any model call, ask: "Have I included every file that could possibly be relevant?" When in doubt, include more files.
- **Strategic Model Selection:** Choose models based on their known strengths. Use models with powerful reasoning for planning and critique, and models with excellent coding skills for implementation.
- **User-Centricity:** The final solution must be maintainable, secure, and perfectly aligned with the user's intended outcome, not just their literal request.
- **Enforce Quality:** If any model provides a low-quality, vague, or incomplete response, you **must** re-prompt it. State specifically how its previous response failed and demand a more rigorous and complete output. Do not accept mediocrity.
- **Consensus Building:** Facilitate a dialogue between models if their outputs conflict. The goal is to arrive at a consensus that represents the best possible solution, potentially using a third model as a tie-breaker if an impasse is reached.
This strategic framework empowers you to dynamically manage the workflow, ensuring a higher quality result than any single model could achieve alone.

1
commands/cancel-ralph.md Symbolic link
View File

@@ -0,0 +1 @@
/home/roman/.claude/skills/plugins/marketplaces/claude-plugins-official/plugins/ralph-loop/commands/cancel-ralph.md

62
commands/clawd.md Normal file
View File

@@ -0,0 +1,62 @@
---
description: Delegate autonomous tasks to Clawd agent via hook wrapper with persistent session context
---
You are invoking the Clawd autonomous agent to handle the user's task.
## Clawd Overview
Clawd is a personal AI assistant with:
- Multi-agent routing and workspaces
- Persistent session context
- Tool access (bash, file operations, browser automation)
- Hook-based integration for reliable execution
## How to Use Clawd from Claude Code
When the user runs `/clawd "<task>"`:
1. **Parse the task** from the user's message
2. **Parse any options**:
- `--agent <id>` or `-a`: Specific agent (default: main)
- `--thinking <level>`: off|minimal|low|medium|high
3. **Execute the clawd-wrapper hook** using the bash tool:
```bash
~/.claude/hooks/clawd-wrapper.sh --task "<task>" --agent <id> --thinking <level>
```
4. **Return the results** to the user
## Examples
```bash
# Basic task
~/.claude/hooks/clawd-wrapper.sh --task "Build a login form"
# With high thinking
~/.claude/hooks/clawd-wrapper.sh --task "Analyze codebase" --thinking high
# Specific agent
~/.claude/hooks/clawd-wrapper.sh --task "Deploy application" --agent ops
```
## Available Agents
- `main` - Default general-purpose agent
- `ops` - Operations and DevOps tasks
- Other configured agents
## User's Task
Execute the following task using Clawd via the hook wrapper:
{{USER_MESSAGE}}
## Instructions
1. Parse the task and any options from the user's message above
2. Construct the appropriate clawd-wrapper command
3. Execute it using the Bash tool
4. Return the complete output to the user
5. If there are errors, help troubleshoot

1
commands/clean_gone.md Symbolic link
View File

@@ -0,0 +1 @@
/home/roman/.claude/skills/plugins/marketplaces/claude-plugins-official/plugins/commit-commands/commands/clean_gone.md

1
commands/cleanup.md Symbolic link
View File

@@ -0,0 +1 @@
/home/roman/.claude/skills/plugins/marketplaces/design-plugins/design-and-refine/commands/cleanup.md

6
commands/code-review-response.md Normal file
View File

@@ -0,0 +1,6 @@
---
description: "Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable. Requires technical rigor and verification, not performative agreement or blind implementation."
disable-model-invocation: true
---
Invoke the superpowers:receiving-code-review skill and follow it exactly as presented to you

1
commands/code-review.md Symbolic link
View File

@@ -0,0 +1 @@
/home/roman/.claude/skills/plugins/marketplaces/claude-plugins-official/plugins/code-review/commands/code-review.md

1
commands/commit-push-pr.md Symbolic link
View File

@@ -0,0 +1 @@
/home/roman/.claude/skills/plugins/marketplaces/claude-plugins-official/plugins/commit-commands/commands/commit-push-pr.md

1
commands/commit.md Symbolic link
View File

@@ -0,0 +1 @@
/home/roman/.claude/skills/plugins/marketplaces/claude-plugins-official/plugins/commit-commands/commands/commit.md

1
commands/configure.md Symbolic link
View File

@@ -0,0 +1 @@
/home/roman/.claude/skills/plugins/marketplaces/claude-plugins-official/plugins/hookify/commands/configure.md

6
commands/debug.md Normal file
View File

@@ -0,0 +1,6 @@
---
description: "Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes. Requires technical rigor and verification."
disable-model-invocation: true
---
Invoke the superpowers:systematic-debugging skill and follow it exactly as presented to you

8
commands/dexto-code.md Normal file
View File

@@ -0,0 +1,8 @@
---
description: "Dexto Code Agent"
---
Use Dexto Code Agent.
**Task:**
{{USER_MESSAGE}}

8
commands/dexto-database.md Normal file
View File

@@ -0,0 +1,8 @@
---
description: "Dexto Database Agent"
---
Use Dexto Database Agent.
**Task:**
{{USER_MESSAGE}}

8
commands/dexto-explore.md Normal file
View File

@@ -0,0 +1,8 @@
---
description: "Dexto Explore Agent"
---
Use Dexto Explore Agent.
**Task:**
{{USER_MESSAGE}}

8
commands/dexto-github.md Normal file
View File

@@ -0,0 +1,8 @@
---
description: "Dexto Github Agent"
---
Use Dexto Github Agent.
**Task:**
{{USER_MESSAGE}}

8
commands/dexto-image-edit.md Normal file
View File

@@ -0,0 +1,8 @@
---
description: "Dexto Image Edit Agent"
---
Use Dexto Image Edit Agent.
**Task:**
{{USER_MESSAGE}}

8
commands/dexto-music.md Normal file
View File

@@ -0,0 +1,8 @@
---
description: "Dexto Music Agent"
---
Use Dexto Music Agent.
**Task:**
{{USER_MESSAGE}}

8
commands/dexto-nano-banana.md Normal file
View File

@@ -0,0 +1,8 @@
---
description: "Dexto Nano Banana Agent"
---
Use Dexto Nano Banana Agent.
**Task:**
{{USER_MESSAGE}}

8
commands/dexto-pdf.md Normal file
View File

@@ -0,0 +1,8 @@
---
description: "Dexto Pdf Agent"
---
Use Dexto Pdf Agent.
**Task:**
{{USER_MESSAGE}}

8
commands/dexto-podcast.md Normal file
View File

@@ -0,0 +1,8 @@
---
description: "Dexto Podcast Agent"
---
Use Dexto Podcast Agent.
**Task:**
{{USER_MESSAGE}}

8
commands/dexto-research.md Normal file
View File

@@ -0,0 +1,8 @@
---
description: "Dexto Research Agent"
---
Use Dexto Research Agent.
**Task:**
{{USER_MESSAGE}}

8
commands/dexto-sora.md Normal file
View File

@@ -0,0 +1,8 @@
---
description: "Dexto Sora Agent"
---
Use Dexto Sora Agent.
**Task:**
{{USER_MESSAGE}}

8
commands/dexto-triage.md Normal file
View File

@@ -0,0 +1,8 @@
---
description: "Dexto Triage Agent"
---
Use Dexto Triage Agent.
**Task:**
{{USER_MESSAGE}}

6
commands/discover-tools.md Normal file
View File

@@ -0,0 +1,6 @@
---
description: "Automatically searches for and installs helpful Claude Code tools/plugins from code.claude.com based on current task context. Use when starting any complex task to ensure optimal tooling is available."
disable-model-invocation: true
---
Invoke the superpowers:tool-discovery-agent skill and follow it exactly as presented to you

1
commands/explain-error.md Symbolic link
View File

@@ -0,0 +1 @@
/home/roman/.claude/skills/plugins/marketplaces/claude-plugins-official/external_plugins/stripe/commands/explain-error.md

1
commands/feature-dev.md Symbolic link
View File

@@ -0,0 +1 @@
/home/roman/.claude/skills/plugins/marketplaces/claude-plugins-official/plugins/feature-dev/commands/feature-dev.md

6
commands/finish-branch.md Normal file
View File

@@ -0,0 +1,6 @@
---
description: "Use when implementation is complete, all tests pass, and you need to decide how to integrate the work. Guides completion of development work by presenting structured options for merge, PR, or cleanup."
disable-model-invocation: true
---
Invoke the superpowers:finishing-a-development-branch skill and follow it exactly as presented to you

1
commands/help.md Symbolic link
View File

@@ -0,0 +1 @@
/home/roman/.claude/skills/plugins/marketplaces/claude-plugins-official/plugins/hookify/commands/help.md

1
commands/hookify.md Symbolic link
View File

@@ -0,0 +1 @@
/home/roman/.claude/skills/plugins/marketplaces/claude-plugins-official/plugins/hookify/commands/hookify.md

1
commands/list.md Symbolic link
View File

@@ -0,0 +1 @@
/home/roman/.claude/skills/plugins/marketplaces/claude-plugins-official/plugins/hookify/commands/list.md

6
commands/multi-brainstorm.md Normal file
View File

@@ -0,0 +1,6 @@
---
description: "Multi-AI brainstorming using Qwen coder-model. Collaborate with multiple AI agents (content, seo, smm, pm, code, design, web, app) for expert-level ideation. Use before any creative work for diverse perspectives."
disable-model-invocation: true
---
Invoke the superpowers:multi-ai-brainstorm skill and follow it exactly as presented to you

1
commands/new-sdk-app.md Symbolic link
View File

@@ -0,0 +1 @@
/home/roman/.claude/skills/plugins/marketplaces/claude-plugins-official/plugins/agent-sdk-dev/commands/new-sdk-app.md

6
commands/pipeline.md Normal file
View File

@@ -0,0 +1,6 @@
---
description: "Build multi-agent pipelines with structured data flow between agents. Use when creating workflows where each agent has a specialized role and passes output to the next agent."
disable-model-invocation: true
---
Invoke the superpowers:agent-pipeline-builder skill and follow it exactly as presented to you

14
commands/prometheus-bug.md Normal file
View File

@@ -0,0 +1,14 @@
---
description: "Analyze and reproduce bugs using Prometheus bug analyzer agent with context retrieval and reproduction steps"
---
Invoke the Prometheus Bug Analyzer to investigate and reproduce the reported bug.
**Task:**
{{USER_MESSAGE}}
**Instructions:**
1. Use ~/.claude/hooks/prometheus-wrapper.sh with --bug mode
2. Retrieve relevant code context
3. Create reproduction steps
4. Generate bug analysis report

14
commands/prometheus-classify.md Normal file
View File

@@ -0,0 +1,14 @@
---
description: "Classify incoming issues as bug, feature, question, or documentation using Prometheus classifier agent"
---
Invoke the Prometheus Issue Classifier to categorize the user's input.
**Task:**
{{USER_MESSAGE}}
**Instructions:**
1. Use ~/.claude/hooks/prometheus-wrapper.sh with --issue-classify mode
2. Analyze the issue type (bug/feature/question/documentation)
3. Provide classification with confidence score
4. Return routing recommendation

14
commands/prometheus-context.md Normal file
View File

@@ -0,0 +1,14 @@
---
description: "Retrieve intelligent code context using Prometheus knowledge graph and semantic search"
---
Invoke the Prometheus Context Provider to retrieve relevant code context.
**Query:**
{{USER_MESSAGE}}
**Instructions:**
1. Use ~/.claude/hooks/prometheus-wrapper.sh with --context mode
2. Search knowledge graph for relevant code
3. Retrieve semantic context
4. Provide structured context with file references

14
commands/prometheus-edit.md Normal file
View File

@@ -0,0 +1,14 @@
---
description: "Generate code edits and patches using Prometheus edit generator with validation"
---
Invoke the Prometheus Edit Generator to create code changes.
**Task:**
{{USER_MESSAGE}}
**Instructions:**
1. Use ~/.claude/hooks/prometheus-wrapper.sh with --edit mode
2. Generate patch with context awareness
3. Validate edit safety
4. Provide diff and application instructions

14
commands/prometheus-feature.md Normal file
View File

@@ -0,0 +1,14 @@
---
description: "Analyze feature requests and create implementation plans using Prometheus feature analyzer agent"
---
Invoke the Prometheus Feature Analyzer to analyze and plan the feature implementation.
**Task:**
{{USER_MESSAGE}}
**Instructions:**
1. Use ~/.claude/hooks/prometheus-wrapper.sh with --feature mode
2. Analyze requirements and dependencies
3. Create implementation plan
4. Identify potential risks and alternatives

14
commands/prometheus-test.md Normal file
View File

@@ -0,0 +1,14 @@
---
description: "Run tests in containerized environment using Prometheus test runner agent"
---
Invoke the Prometheus Test Runner to execute and validate tests.
**Task:**
{{USER_MESSAGE}}
**Instructions:**
1. Use ~/.claude/hooks/prometheus-wrapper.sh with --test mode
2. Set up containerized test environment
3. Execute test suite
4. Provide detailed results and coverage

105
commands/prometheus.md Normal file
View File

@@ -0,0 +1,105 @@
---
description: Delegate to Prometheus multi-agent code analysis system for issue resolution, feature implementation, and intelligent code context retrieval
disable-model-invocation: true
---
# Prometheus Multi-Agent Code Analysis System
Prometheus is a production-ready AI-powered platform that uses multi-agent systems and unified knowledge graphs to perform intelligent operations on codebases.
## Capabilities
- **Automated Issue Resolution**: End-to-end bug fixing with reproduction, patch generation, and validation
- **Feature Implementation**: Context-aware feature analysis and implementation planning
- **Intelligent Context Retrieval**: Graph-based semantic search over codebase structure
- **Multi-Agent Orchestration**: Coordinated workflow between specialized agents
- **Knowledge Graph Integration**: Neo4j-powered code representation
- **Question Answering**: Natural language queries with tool-augmented agents
## Agent Types
1. **Issue Classifier**: Categorizes incoming issues (bug/feature/question/doc)
2. **Bug Analyzer**: Analyzes and reproduces bugs
3. **Feature Analyzer**: Plans feature implementations
4. **Context Provider**: Retrieves relevant code context
5. **Edit Generator**: Creates code patches
6. **Test Runner**: Validates changes in containerized environment
## Usage
### Basic Issue Analysis
```bash
/prometheus "Analyze this issue: Login fails after password reset"
```
### Bug Fix Mode
```bash
/prometheus --bug "Fix the authentication bug in src/auth/login.py"
```
### Feature Implementation
```bash
/prometheus --feature "Implement two-factor authentication"
```
### Code Context Query
```bash
/prometheus --query "How does the payment processing work?"
```
### With Repository
```bash
/prometheus --repo /path/to/repo "Analyze the codebase structure"
```
## Integration Points
- **Knowledge Graph**: Neo4j for code structure and semantic analysis
- **Docker**: Containerized testing environment
- **Git**: Version control operations
- **AST Parsing**: Multi-language code analysis
- **LangGraph**: State machine orchestration
## Output
Prometheus provides:
- Issue classification and analysis
- Bug reproduction steps
- Generated patches with validation
- Context-aware recommendations
- Test results and coverage
## Examples
```bash
# Analyze a GitHub issue
/prometheus "Issue #123: Memory leak in data processing pipeline"
# Implement a feature
/prometheus --feature "Add rate limiting to API endpoints"
# Code understanding
/prometheus --query "Explain the authentication flow"
# Bug fix with context
/prometheus --bug --repo ./myapp "Fix null pointer in user service"
```
## Configuration
Prometheus uses:
- `~/.claude/prometheus/` - Installation directory
- `~/.claude/prometheus/venv/` - Python virtual environment
- `~/.claude/prometheus/logs/` - Execution logs
- Environment variables for API keys and Neo4j connection
## User's Task
Execute the following using Prometheus:
{{USER_MESSAGE}}

1
commands/ralph-loop.md Symbolic link
View File

@@ -0,0 +1 @@
/home/roman/.claude/skills/plugins/marketplaces/claude-plugins-official/plugins/ralph-loop/commands/ralph-loop.md

21
commands/ralph.md Executable file
View File

@@ -0,0 +1,21 @@
---
description: "RalphLoop 'Tackle Until Solved' - Enhanced autonomous orchestrator with access to Clawd, Prometheus, Dexto. Routes to best agent automatically or orchestrates multi-agent workflows."
---
Invoke Enhanced Ralph with full agent orchestration capabilities.
Ralph now has access to ALL integrated agents:
- **Clawd** - Autonomous task execution
- **Prometheus** - Code analysis, bug fixing, features
- **Dexto** - 12 specialized agents (code, github, pdf, images, video, music, etc.)
Ralph will:
1. Analyze task requirements
2. Select best agent automatically (confidence threshold: 70%)
3. Orchestrate multi-agent workflows for complex tasks
4. Execute with continuous improvement loops
User's task:
{{USER_MESSAGE}}
Execute this task using the best available agent(s).

1
commands/review-pr.md Symbolic link
View File

@@ -0,0 +1 @@
/home/roman/.claude/skills/plugins/marketplaces/claude-plugins-official/plugins/pr-review-toolkit/commands/review-pr.md

6
commands/review.md Normal file
View File

@@ -0,0 +1,6 @@
---
description: "Use when completing tasks, implementing major features, or before merging to verify work meets requirements."
disable-model-invocation: true
---
Invoke the superpowers:requesting-code-review skill and follow it exactly as presented to you

1
commands/set-custom-rules.md Symbolic link
View File

@@ -0,0 +1 @@
/home/roman/.claude/skills/plugins/claude-code-safety-net/commands/set-custom-rules.md

1
commands/set-statusline.md Symbolic link
View File

@@ -0,0 +1 @@
/home/roman/.claude/skills/plugins/claude-code-safety-net/commands/set-statusline.md

1
commands/setup.md Symbolic link
View File

@@ -0,0 +1 @@
/home/roman/.claude/skills/plugins/claude-hud/commands/setup.md

1
commands/start.md Symbolic link
View File

@@ -0,0 +1 @@
/home/roman/.claude/skills/plugins/marketplaces/design-plugins/design-and-refine/commands/start.md

6
commands/tdd.md Normal file
View File

@@ -0,0 +1,6 @@
---
description: "Use when implementing any feature or bugfix, before writing implementation code. Follows test-driven development methodology."
disable-model-invocation: true
---
Invoke the superpowers:test-driven-development skill and follow it exactly as presented to you

1
commands/test-cards.md Symbolic link
View File

@@ -0,0 +1 @@
/home/roman/.claude/skills/plugins/marketplaces/claude-plugins-official/external_plugins/stripe/commands/test-cards.md

6
commands/ui-ux.md Normal file
View File

@@ -0,0 +1,6 @@
---
description: "UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, 9 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code."
disable-model-invocation: true
---
Invoke the superpowers:ui-ux-pro-max skill and follow it exactly as presented to you

1
commands/uninstall.md Symbolic link
View File

@@ -0,0 +1 @@
/home/roman/.claude/skills/plugins/claude-delegator/commands/uninstall.md

1
commands/verify-custom-rules.md Symbolic link
View File

@@ -0,0 +1 @@
/home/roman/.claude/skills/plugins/claude-code-safety-net/commands/verify-custom-rules.md

6
commands/verify.md Normal file
View File

@@ -0,0 +1,6 @@
---
description: "Use when about to claim work is complete, fixed, or passing, before committing or creating PRs. Evidence before assertions always."
disable-model-invocation: true
---
Invoke the superpowers:verification-before-completion skill and follow it exactly as presented to you

6
commands/worktree.md Normal file
View File

@@ -0,0 +1,6 @@
---
description: "Use when starting feature work that needs isolation from current workspace or before executing implementation plans. Creates isolated git worktrees with smart directory selection and safety verification."
disable-model-invocation: true
---
Invoke the superpowers:using-git-worktrees skill and follow it exactly as presented to you

251
dexto/AGENTS.md Normal file
View File

@@ -0,0 +1,251 @@
# Dexto Development Guidelines for AI Assistants
This repo is reviewed by automated agents (including CodeRabbit). This file is the source of truth for repo-wide conventions and review expectations.
**Package manager: pnpm** (do not use npm/yarn)
## Code Quality Requirements
Before completing significant tasks, prompt the user to ask if they want to run:
```bash
/quality-checks
```
This runs `scripts/quality-checks.sh` for build, tests, lint, and typecheck. See `.claude/commands/quality-checks.md`.
## General Rules
- Optimize for correctness. Use facts and code as the source of truth.
- Read relevant code before recommending changes. Prefer grep/glob + direct file references over assumptions.
- If something requires assumptions, state them and ask for confirmation.
- Don't communicate to the user via code comments. Comments are for future readers of the code, not for explaining decisions to the user.
## Stack Rules (important)
These rules are intended to prevent stack fragmentation and review churn.
### WebUI (`packages/webui`)
- Build tool: **Vite**
- Routing: **TanStack Router** (`@tanstack/react-router`). Do not introduce `react-router-dom` or other routing systems unless explicitly migrating.
- Server-state/data fetching: **TanStack Query** (`@tanstack/react-query`). Prefer it for request caching, invalidation, and async state.
- Client-side state: Zustand exists; prefer it only for genuinely client-only state (UI preferences, local toggles). Avoid duplicating server state into stores.
### Server (`packages/server`)
- HTTP API: **Hono** routes live in `packages/server/src/hono/routes/*.ts`.
- Error mapping middleware: `packages/server/src/hono/middleware/error.ts`.
### Core (`packages/core`)
- Core is the business logic layer. Keep policy, validation boundaries, and reusable services here.
### CLI (`packages/cli`)
- Entry point: `packages/cli/src/cli/index.ts`
- Static commands (e.g., `dexto init`, `dexto setup`): `packages/cli/src/cli/commands/`
- Interactive CLI commands (e.g., `/help`, `/compact`): `packages/cli/src/cli/commands/interactive-commands/`
- Ink-based UI components: `packages/cli/src/cli/ink-cli/`
### Other Important Packages
- **`@dexto/client-sdk`**: Lightweight type-safe client for the Dexto API (Hono-based). Use for external integrations.
- **`@dexto/agent-management`**: Agent registry, config discovery, preferences, and agent resolution logic.
- **`@dexto/analytics`**: Shared PostHog analytics utilities for CLI and WebUI (opt-in telemetry).
- **`@dexto/registry`**: Shared registry data (MCP server presets, etc.) for CLI and WebUI.
- **`@dexto/tools-*`**: Modular tool packages (`tools-filesystem`, `tools-process`, `tools-todo`, `tools-plan`). Each provides a tool provider that registers with the core tool registry.
### Images (`packages/image-*`)
Images are pre-configured bundles of providers, tools, and defaults for specific deployment targets. They use `defineImage()` from core.
- **`@dexto/image-local`**: Local development image with filesystem/process tools, SQLite storage.
- **`@dexto/image-bundler`**: Build tool for bundling images (`dexto-bundle` CLI).
Image definition files use the convention `dexto.image.ts` and register providers (blob stores, custom tools) as side-effects when imported.
### Adding New Packages
All `@dexto/*` packages use **fixed versioning** (shared version number).
When creating a new package:
1. Add the package name to the `fixed` array in `.changeset/config.json`
2. Set its `version` in `package.json` to match other packages (check `packages/core/package.json`)
## Avoiding Duplication (repo-wide)
**Before adding any new helper/utility/service:**
1. Search the codebase first (glob/grep for similar patterns).
2. Prefer extending existing code over creating new.
3. If new code is necessary, justify why existing code doesn't work.
This applies everywhere (core, server, cli, webui). Violations will be flagged in review.
## Architecture & Design Patterns
### API / Server Layer
- Routes should be thin wrappers around core capabilities (primarily `DextoAgent` + core services).
- Keep business logic out of routes; keep route code focused on:
- request parsing/validation
- calling core
- mapping errors + returning responses
- `DextoAgent` class should also not have too much business logic; should call helper methods within services it owns.
### Service Initialization
- **Config file is source of truth**: Agent YAML files in `agents/` directory (e.g., `agents/coding-agent/coding-agent.yml`).
- **Override pattern for advanced use**: use `InitializeServicesOptions` only for top-level services (avoid wiring every internal dependency).
- **CLI Config Enrichment**: CLI adds per-agent paths (logs, database, blobs) via `enrichAgentConfig()` before agent initialization.
- Source: `packages/agent-management/src/config/config-enrichment.ts`
### Execution Context Detection
Dexto infers its execution environment to enable context-aware defaults and path resolution. Use these utilities when behavior should differ based on how dexto is running.
**Context types:**
- `dexto-source`: Running within the dexto monorepo itself (development)
- `dexto-project`: Running in a project that has dexto as a dependency
- `global-cli`: Running as globally installed CLI or in a non-dexto project
**Key files:**
- `packages/core/src/utils/execution-context.ts` - Context detection
- `packages/core/src/utils/path.ts` - Context-aware path resolution
- `packages/cli/src/cli/utils/api-key-setup.ts` - Context-aware setup UX
## Zod / Schema Design
- Always use `.strict()` for configuration objects (reject typos/unknown fields).
- Prefer `discriminatedUnion` over `union` for clearer errors.
- Describe fields with `.describe()` where it improves usability.
- Prefer sensible defaults via `.default()`.
- Use `superRefine` for cross-field validation.
Type extraction conventions (repo rule):
- Use `z.input<typeof Schema>` for raw/unvalidated input types.
- Use `z.output<typeof Schema>` for validated/output types.
- Do not use `z.infer` (lint-restricted).
## Result Pattern & Validation Boundary
### Core Principles
- **`DextoAgent` is the validation boundary**: public-facing methods validate inputs; internal layers can assume validated inputs.
- Internal validation helpers should return Result-style objects; public methods throw typed errors.
### Result Helpers
Use standardized helpers from: `packages/core/src/utils/result.ts`
- `ok(data, issues?)`
- `fail(issues)`
- `hasErrors(issues)`
- `splitIssues(issues)`
- `zodToIssues(zodError)`
## Error Handling
### Core Error Classes
- `DextoRuntimeError`: single runtime failure (I/O, network, invariant violation)
- `DextoValidationError`: multiple validation issues
### Rules
- Avoid `throw new Error()` in `packages/core`. Prefer typed errors.
- Non-core packages may use plain `Error` when a typed error is not available.
- Use module-specific **error factory** pattern for new modules.
- Reference examples:
- `packages/core/src/config/errors.ts`
- `packages/core/src/logger/v2/errors.ts`
- `packages/core/src/storage/errors.ts`
- `packages/core/src/telemetry/errors.ts`
- **Exemption**: Build-time CLI tools and development tooling (bundlers, compilers, build scripts) are exempt from the strict `DextoRuntimeError`/`DextoValidationError` requirement. Plain `Error` is acceptable for build tool failures to align with standard build tool practices (tsc, esbuild, vite).
### Server/API error mapping
- Source of truth: `mapErrorTypeToStatus()` in `packages/server/src/hono/middleware/error.ts`
## Imports / ESM
- In `packages/core`, local relative imports must include `.js` in the TypeScript source for Node ESM output compatibility.
- Do not add `.js` to package imports (e.g. `zod`, `hono`, `@dexto/*`).
## OpenAPI Documentation
- Never directly edit `docs/static/openapi/openapi.json` (generated file).
- OpenAPI is generated from Hono route definitions in `packages/server/src/hono/routes/*.ts`.
Update process:
1. Modify route definitions / Zod schemas in `packages/server/src/hono/routes/*.ts`
2. Run `pnpm run sync-openapi-docs`
3. Verify the generated output includes your changes
## Logging
The repo contains logger v1 and logger v2 APIs (core). Prefer patterns compatible with structured logging.
- Prefer: `logger.info('Message', { contextKey: value })` (structured context as the second parameter where supported)
- Avoid: `logger.error('Failed:', err)` style extra-arg logging; it's ambiguous across logger versions/transports.
- Template literals are fine when interpolating values:
- `logger.info(\`Server running at \${url}\`)`
Colors:
- Color formatting exists (chalk-based), but treat color choice as optional and primarily CLI-facing (don't encode “must use exact color X” rules in new code unless the existing subsystem already does).
Browser safety:
- `packages/core/src/logger/logger.ts` is Node-oriented (fs/path/winston). Be careful not to import Node-only runtime modules into `packages/webui` bundles. Prefer `import type` when consuming core types from the WebUI.
## TypeScript Guidelines
- Strict null safety: handle `null` / `undefined` explicitly.
- Avoid `any` across the repo.
- Prefer `unknown` + type guards.
- If `any` is unavoidable (third-party typing gaps / boundary code), keep the usage local and justify it.
- In tests, prefer `@ts-expect-error` over `as any` when intentionally testing invalid inputs.
- Avoid introducing optional parameters unless necessary; prefer explicit overloads or separate functions if it improves call-site clarity.
## Module Organization
- Selective barrel strategy: only add `index.ts` at real public module boundaries.
- Prefer direct imports internally; avoid deep re-export chains.
- Avoid wildcard exports; prefer explicit named exports.
- Watch for mega barrels (>20 symbols or >10 files) and split if needed.
## Git / PR Standards
- Never use `git add .` or `git add -A`. Stage explicit files/paths only.
- Always inspect staged files before committing.
- Never amend commits (`git commit --amend`). Create new commits instead.
- Don't include AI-generated footers in commits/PRs.
- Keep commit messages technical and descriptive.
## Documentation Changes
- Always request user review before committing documentation changes.
- Never auto-commit documentation updates.
- Keep documentation user-focused; avoid exposing unnecessary internal complexity.
## Testing
Test types:
- Unit: `*.test.ts`
- Integration: `*.integration.test.ts`
Test location: Co-locate tests with source files (e.g., `foo.ts` → `foo.test.ts` in same directory).
Common commands:
- `pnpm test`
- `pnpm run test:unit`
- `pnpm run test:integ`
When fixing bugs, add regression coverage where feasible.
## Maintaining This File
Keep `AGENTS.md` updated when:
- Adding a new package: add a brief description under the appropriate Stack Rules section
- Architecture boundaries change (server/webui/cli)
- Repo-wide conventions change (lint/type patterns, errors, OpenAPI generation)
- File paths referenced here move

1
dexto/CLAUDE.md Symbolic link
View File

@@ -0,0 +1 @@
AGENTS.md

128
dexto/CODE_OF_CONDUCT.md Normal file
View File

@@ -0,0 +1,128 @@
# Contributor Covenant Code of Conduct
## Our Pledge
We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, religion, or sexual identity
and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.
## Our Standards
Examples of behavior that contributes to a positive environment for our
community include:
* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
* Focusing on what is best not just for us as individuals, but for the
overall community
Examples of unacceptable behavior include:
* The use of sexualized language or imagery, and sexual attention or
advances of any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email
address, without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Enforcement Responsibilities
Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.
Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.
## Scope
This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
founders@trytruffle.ai .
All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the
reporter of any incident.
## Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:
### 1. Correction
**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.
**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.
### 2. Warning
**Community Impact**: A violation through a single incident or series
of actions.
**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or
permanent ban.
### 3. Temporary Ban
**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.
**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within
the community.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.0, available at
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
Community Impact Guidelines were inspired by [Mozilla's code of conduct
enforcement ladder](https://github.com/mozilla/diversity).
[homepage]: https://www.contributor-covenant.org
For answers to common questions about this code of conduct, see the FAQ at
https://www.contributor-covenant.org/faq. Translations are available at
https://www.contributor-covenant.org/translations.

525
dexto/CONTRIBUTING.md Normal file
View File

@@ -0,0 +1,525 @@
# Contributing to Dexto
We welcome contributions! This guide will help you get started with contributing to the Dexto project.
## Table of Contents
- [Getting Started](#getting-started)
- [Contributing MCPs and Example Agents](#contributing-mcps-and-example-agents)
- [Development Setup](#development-setup)
- [Making Changes](#making-changes)
- [Submitting a Pull Request](#submitting-a-pull-request)
- [Code Standards](#code-standards)
- [Commit Guidelines](#commit-guidelines)
- [Changesets](#changesets)
## Getting Started
Before contributing, please:
1. Read our [Code of Conduct](./CODE_OF_CONDUCT.md)
2. Check existing [issues](https://github.com/truffle-ai/dexto/issues) and [pull requests](https://github.com/truffle-ai/dexto/pulls)
3. Open an issue for discussion on larger changes or enhancements
## Contributing MCPs and Example Agents
We especially encourage contributions that expand Dexto's ecosystem! Here are three ways you can contribute:
### 1. Adding New MCPs to the WebUI Registry
Help other users discover and use new MCP servers by adding them to our built-in registry.
**How to add an MCP to the registry:**
1. Edit `src/app/webui/lib/server-registry-data.json`
2. Add a new entry following this structure:
```json
{
"id": "unique-server-id",
"name": "Display Name",
"description": "Brief description of what this server does",
"category": "productivity|research|creative|development|data|communication",
"icon": "📁",
"config": {
"type": "stdio|http|sse",
"command": "npx|uvx|python",
"args": ["-y", "package-name"],
"env": {
"API_KEY": ""
},
"timeout": 30000
},
"tags": ["tag1", "tag2"],
"isOfficial": false,
"isInstalled": false,
"requirements": {
"platform": "all|windows|mac|linux",
"node": ">=20.0.0",
"python": ">=3.10"
},
"author": "Your Name",
"homepage": "https://github.com/your-repo",
"matchIds": ["server-id"]
}
```
**Categories:**
- `productivity` - File operations, task management, workflow tools
- `research` - Search, data analysis, information gathering
- `creative` - Image editing, music creation, content generation
- `development` - Code analysis, debugging, development tools
- `data` - Data processing, analytics, databases
- `communication` - Email, messaging, collaboration tools
**Configuration Types:**
- **Stdio (Node.js)**: `{"type": "stdio", "command": "npx", "args": ["-y", "package-name"]}`
- **Stdio (Python)**: `{"type": "stdio", "command": "uvx", "args": ["package-name"]}`
- **HTTP**: `{"type": "http", "baseUrl": "https://api.example.com/mcp"}`
- **SSE**: `{"type": "sse", "url": "https://api.example.com/mcp-sse"}`
### 2. Creating Example Agents
Showcase how to use MCPs by creating example agents in the `agents/` directory.
**How to create an example agent:**
1. Create a new directory: `agents/your-agent-name/`
2. Add a `your-agent-name.yml` configuration file
3. Include a `README.md` with setup instructions and usage examples
4. Follow the existing agent structure (see `agents/examples/` for reference)
**Example agent structure:**
```
agents/your-agent-name/
├── your-agent-name.yml # Main configuration
├── README.md # Setup and usage guide
└── data/ # Optional: sample data
└── example.json
```
**Configuration template:**
```yaml
# Your Agent Name
# Brief description of what this agent does
systemPrompt: |
You are a [Agent Name] specialized in [purpose]. You have access to [MCP servers] that allow you to:
## Your Capabilities
- [List key capabilities]
- [More capabilities]
## How You Should Behave
- [Behavior guidelines]
- [Usage examples]
mcpServers:
your-mcp:
type: stdio
command: npx
args:
- -y
- "package-name"
env:
API_KEY: $YOUR_API_KEY
llm:
provider: openai
model: gpt-5-mini
apiKey: $OPENAI_API_KEY
storage:
cache:
type: in-memory
database:
type: sqlite
path: .dexto/database/your-agent.db
```
**README template:**
```markdown
# Your Agent Name
Brief description of what this agent does and why it's useful.
## Features
- Feature 1
- Feature 2
## Setup
1. Install dependencies: `npm install`
2. Set environment variables: `export YOUR_API_KEY=your-key`
3. Run the agent: `dexto --agent your-agent-name.yml`
## Usage Examples
- "Example command 1"
- "Example command 2"
## Requirements
- Node.js >= 20.0.0
- Your API key
```
### 3. Adding Agents to the Official Registry
Once you've created a comprehensive example agent, you can add it to the official agent registry so users can discover and install it with `dexto install`.
**How to add an agent to the registry:**
1. Create your agent in `agents/your-agent-name/` (following step 2 above)
2. Edit `agents/agent-registry.json` and add your agent entry
3. Edit `packages/cli/scripts/copy-agents.ts` and add your agent to the `AGENTS_TO_COPY` array
4. Test the build to ensure your agent is properly copied
5. Open a pull request with:
- Link to your agent directory
- Description of the agent's purpose and value
- Screenshots or demos if applicable
- Evidence of testing and documentation
**Registry Entry Structure (`agents/agent-registry.json`):**
```json
{
"your-agent-id": {
"id": "your-agent-id",
"name": "Your Agent Name",
"description": "Brief description of what this agent does and its key capabilities",
"author": "Your Name or Organization",
"tags": ["category", "use-case", "technology"],
"source": "your-agent-name/",
"main": "your-agent-name.yml"
}
}
```
**Field Guidelines:**
- **id**: Lowercase, hyphenated identifier (e.g., `database-agent`, `podcast-agent`)
- **name**: Human-readable display name (e.g., `Database Agent`, `Podcast Agent`)
- **description**: Clear, concise description of purpose and capabilities (1-2 sentences)
- **author**: Your name, organization, or `Truffle AI` for official agents
- **tags**: 3-6 relevant tags for categorization and search:
- **Category tags**: `database`, `images`, `video`, `audio`, `coding`, `documents`, etc.
- **Technology tags**: `gemini`, `openai`, `anthropic`, `mcp`, etc.
- **Use case tags**: `creation`, `analysis`, `editing`, `generation`, `support`, etc.
- **source**: Directory path relative to `agents/` folder (ends with `/` for directories)
- **main**: Main configuration file name (e.g., `agent.yml`, `your-agent-name.yml`)
**Tag Examples:**
```json
// Content creation agent
"tags": ["images", "generation", "editing", "ai", "gemini"]
// Development agent
"tags": ["coding", "development", "software", "programming"]
// Data analysis agent
"tags": ["database", "sql", "data", "queries", "analysis"]
// Multi-modal agent
"tags": ["audio", "tts", "speech", "multi-speaker", "gemini"]
```
**Complete Example:**
```json
{
"music-agent": {
"id": "music-agent",
"name": "Music Agent",
"description": "AI agent for music creation and audio processing",
"author": "Truffle AI",
"tags": ["music", "audio", "creation", "sound"],
"source": "music-agent/",
"main": "music-agent.yml"
}
}
```
**Single-File vs Directory Agents:**
- **Directory agent** (with multiple files):
```json
{
"source": "your-agent-name/",
"main": "agent.yml"
}
```
- **Single-file agent** (all in one YAML):
```json
{
"source": "your-agent.yml"
}
```
Note: `main` field is omitted for single-file agents.
**Build Script Configuration (`packages/cli/scripts/copy-agents.ts`):**
Add your agent to the `AGENTS_TO_COPY` array:
```typescript
const AGENTS_TO_COPY = [
// Core files
'agent-registry.json',
'agent-template.yml',
// Agent directories
'coding-agent/',
'database-agent/',
'your-agent-name/', // Add your agent here
// ... other agents
];
```
**Important Notes:**
- Directory agents should end with `/` (e.g., `'your-agent-name/'`)
- Single-file agents should NOT have a trailing slash (e.g., `'your-agent.yml'`)
- The script copies agents to `packages/cli/dist/agents/` during build
- Run `pnpm run build` to test that your agent is properly copied
**Criteria for registry acceptance:**
- Solves a common, well-defined problem
- Has clear documentation and examples
- Works reliably across different environments
- Provides significant value to the Dexto community
- Follows all coding standards and best practices
- Demonstrates unique capabilities or fills a gap
### Documentation
- Update relevant documentation in `/docs` folder
- Include clear examples in your contributions
- Follow the existing documentation structure
*Tip:* Check out existing examples in `agents/examples/` and `agents/database-agent/` for inspiration!
## Development Setup
### Prerequisites
- Node.js >= 20.0.0
- Git
### Fork and Clone
1. Fork the repository to your GitHub account
2. Clone your fork:
```bash
git clone https://github.com/your-username/dexto.git
cd dexto
```
3. Add upstream remote:
```bash
git remote add upstream https://github.com/truffle-ai/dexto.git
```
### Install Dependencies
```bash
# Enable Corepack (built into Node.js 16+)
corepack enable
# Install dependencies (uses correct pnpm version automatically)
pnpm install
# Build all packages
pnpm run build
```
**Note**: Corepack ensures everyone uses the same pnpm version (10.12.4) as specified in package.json.
### Development Workflow
For detailed development workflows, see [DEVELOPMENT.md](./DEVELOPMENT.md). Quick start:
```bash
# Run development server with hot reload
pnpm run dev
# Or create a global symlink for CLI development
pnpm run link-cli
```
## Making Changes
### Create a Feature Branch
```bash
# Update your fork
git checkout main
git pull upstream main
# Create a new branch
git checkout -b feature/your-branch-name
```
### Monorepo Structure
Dexto is a monorepo with three main packages:
- `packages/core` - Core business logic (@dexto/core)
- `packages/cli` - CLI application (dexto)
- `packages/webui` - Web interface (@dexto/webui)
Make changes in the appropriate package(s).
### Code Quality Checks
Before committing, ensure your code passes all checks:
```bash
# Type checking
pnpm run typecheck
# Run tests
pnpm run test
# Fix linting issues
pnpm run lint:fix
# Format code
pnpm run format
# Full validation (recommended before commits)
pnpm run build:check
```
## Submitting a Pull Request
### 1. Create a Changeset
For any changes that affect functionality:
```bash
pnpm changeset
```
Follow the prompts to:
- Select affected packages
- Choose version bump type (patch/minor/major)
- Describe your changes
This creates a file in `.changeset/` that must be committed with your PR.
### 2. Commit Your Changes
```bash
# Stage your changes
git add .
# Commit with a descriptive message
git commit -m "feat(core): add new validation helper"
```
## Commit Guidelines
#### Commit Message Format
We follow [Conventional Commits](https://www.conventionalcommits.org/):
```
type(scope): subject
body (optional)
footer (optional)
```
Types:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Code style changes (formatting, semicolons, etc.)
- `refactor`: Code refactoring
- `perf`: Performance improvements
- `test`: Test additions or fixes
- `chore`: Build process or auxiliary tool changes
Examples:
```bash
feat(cli): add new agent command
fix(core): resolve memory leak in storage manager
docs: update installation instructions
```
### 3. Push and Create PR
```bash
# Push your branch
git push origin feature/your-branch-name
```
Then create a Pull Request on GitHub with:
- Clear title following commit message format
- Description of changes and motivation
- Link to related issue (if applicable)
- Screenshots (for UI changes)
### PR Requirements
Your PR must:
- ✅ Include a changeset (for functional changes)
- ✅ Pass all CI checks
- ✅ Have no merge conflicts
- ✅ Follow code standards
- ✅ Include tests for new functionality
## Code Standards
### TypeScript
- Use strict TypeScript settings
- Avoid `any` types
- Handle null/undefined cases explicitly
- Add JSDoc comments for public APIs
### Error Handling
- Use typed error classes from `packages/core/src/errors/`
- Never use plain `Error` or `throw new Error()`
- Include error context and helpful messages
### Testing
- Unit tests: `*.test.ts`
- Integration tests: `*.integration.test.ts`
- Aim for high coverage of business logic
- Test error cases and edge conditions
### Documentation
- Update relevant documentation with your changes
- Add inline comments for complex logic
- Update README if adding new features
## Changesets
We use [Changesets](https://github.com/changesets/changesets) to manage versions and changelogs.
### When to Add a Changeset
Add a changeset when you:
- Add a new feature
- Fix a bug
- Make breaking changes
- Change public APIs
### When NOT to Add a Changeset
Don't add a changeset for:
- Documentation updates (unless API docs)
- Internal refactoring with no external impact
- Test additions
- Development tooling changes
### Version Bumps
- **Patch** (0.0.X): Bug fixes, minor improvements
- **Minor** (0.X.0): New features, backward compatible
- **Major** (X.0.0): Breaking changes
## Questions?
- Check [DEVELOPMENT.md](./DEVELOPMENT.md) for development workflows
- Open an issue for bugs or feature requests
- Join our Discord community for discussions
- Review existing PRs for examples
Thank you for contributing to Dexto! 🚀
*Tip:* Open an issue first for discussion on larger enhancements or proposals.

337
dexto/DEVELOPMENT.md Normal file
View File

@@ -0,0 +1,337 @@
# Development Guide
This guide covers development workflows for working on the Dexto codebase.
## Table of Contents
- [Project Structure](#project-structure)
- [Development Setup](#development-setup)
- [Development Workflows](#development-workflows)
- [Build Commands](#build-commands)
- [Testing](#testing)
- [Code Quality](#code-quality)
- [Publishing](#publishing)
## Project Structure
Dexto is a monorepo using pnpm workspaces with the following structure:
```
dexto/
├── packages/
│ ├── core/ # @dexto/core - Core business logic
│ ├── cli/ # dexto - CLI application
│ └── webui/ # @dexto/webui - Next.js web interface
├── scripts/ # Build and development scripts
├── agents/ # Agent configurations
└── docs/ # Documentation
```
### Package Dependencies
- `dexto` (CLI) depends on `@dexto/core`
- `@dexto/webui` is embedded into CLI at build time
- All packages version together (fixed versioning)
## Development Setup
### Prerequisites
- Node.js >= 20.0.0
- pnpm (automatically managed via Corepack)
### Initial Setup
```bash
# Clone the repository
git clone https://github.com/truffle-ai/dexto.git
cd dexto
# Enable Corepack (if not already enabled) - this picks pnpm version
corepack enable
# Install dependencies (Corepack will use the correct pnpm version)
pnpm install
# Build all packages
pnpm run build
```
## Development Workflows
### 1. Hot Reload Development (Recommended)
Best for frontend development with automatic reload:
```bash
pnpm run dev
```
This command:
- Builds core and CLI packages
- Runs API server on port 3001 (from built dist)
- Runs WebUI dev server on port 3000 (with hot reload)
- Prefixes output with `[API]` and `[UI]` for clarity
- **Automatically sets `DEXTO_DEV_MODE=true`** to use repository agent configs
Access:
- API: http://localhost:3001
- WebUI: http://localhost:3000
### 2. Symlink Development
Best for CLI development with instant changes:
```bash
# Create global symlink (full build with WebUI)
pnpm run link-cli
# Create global symlink (fast, no WebUI)
pnpm run link-cli-fast
# Remove symlink
pnpm run unlink-cli
```
Now `dexto` command uses your local development code directly.
### 3. Production-like Testing
Test the actual installation experience:
```bash
# Install globally from local build (full)
pnpm run install-cli
# Install globally from local build (fast, no WebUI)
pnpm run install-cli-fast
```
This creates tarballs and installs them globally, simulating `npm install -g dexto`.
### Switching Between Workflows
The `link-cli` and `install-cli` commands are mutually exclusive:
- Running `link-cli` removes any npm installation
- Running `install-cli` removes any pnpm symlink
- Use `unlink-cli` to remove everything
## Build Commands
### Complete Builds
```bash
# Full build with cleaning
pnpm run build
# Build all packages without cleaning
pnpm run build:all
# Build with type checking
pnpm run build:check
```
### Package-Specific Builds
```bash
# Build individual packages
pnpm run build:core
pnpm run build:cli
pnpm run build:webui
# Build CLI and its dependencies only (no WebUI)
pnpm run build:cli-only
```
### WebUI Embedding
The WebUI is embedded into the CLI's dist folder during build:
```bash
# Embed WebUI into CLI dist (run after building WebUI)
pnpm run embed-webui
```
## Testing
### Automated Tests
```bash
# Run all tests
pnpm test
# Run unit tests only
pnpm run test:unit
# Run integration tests only
pnpm run test:integ
# Run tests with coverage
pnpm run test:ci
```
### Manual testing
1. Common commands
```bash
cd ~
dexto --help
dexto "what is the current time"
dexto "list files in current directory"
# Test other model override in CLI
dexto -m gpt-5-mini "what is the current date"
# Test web mode
dexto
# Test discord bot mode (requires additional setup)
dexto --mode discord
# Test telegram bot mode (requires additional setup)
dexto --mode telegram
```
2. Execution contexts
Dexto CLI operates differently based on the directory you are running in.
- source context -> when Dexto CLI is run in the source repository
- global context -> when Dexto CLI is run outside the source repository
- project context -> when Dexto CLI is run in a project that consumes @dexto dependencies
Based on execution context, Dexto CLI will use defaults for log path, default agent/agent registry.
Run the CLI in different places and see the console logs to understand this.
Test above commands in different execution contexts for manual testing coverage.
**Developer Mode Environment Variable:**
When running `dexto` from within this repository, it normally uses your `dexto setup` preferences and global `~/.dexto` directory. To force isolated testing with repository files:
```bash
export DEXTO_DEV_MODE=true # Use repo configs and local .dexto directory
```
**DEXTO_DEV_MODE Behavior:**
- **Agent Config**: Uses `agents/coding-agent/coding-agent.yml` from repo (instead of `~/.dexto/agents/`)
- **Logs/Database**: Uses `repo/.dexto/` (instead of `~/.dexto/`)
- **Preferences**: Skips global setup validation
- **Use Case**: Isolated testing and development on Dexto itself
**Note**: `pnpm run dev` automatically sets `DEXTO_DEV_MODE=true`, so the development server always uses repository configs and local storage.
## Code Quality
### Type Checking
```bash
# Type check all packages
pnpm run typecheck
# Type check with file watching
pnpm run typecheck:watch
# Type check specific package
pnpm run typecheck:core
```
### Linting
```bash
# Run linter
pnpm run lint
# Fix linting issues
pnpm run lint:fix
```
### Pre-commit Checks
Before committing, always run:
```bash
pnpm run build:check # Typecheck + build
pnpm test # Run tests
pnpm run lint # Check linting
```
## Publishing
### Changeset Workflow
We use [Changesets](https://github.com/changesets/changesets) for version management:
1. **Create a changeset** for your changes:
```bash
pnpm changeset
```
2. **Select packages** affected by your change
3. **Choose version bump** (patch/minor/major)
4. **Write summary** of your changes
### Version Strategy
- **Fixed versioning**: All packages version together
- `@dexto/core` and `dexto` always have the same version
- `@dexto/webui` is private and not published
### Publishing Process
Publishing is automated via GitHub Actions:
1. Merge PR with changeset
2. Bot creates "Version Packages" PR
3. Merge version PR to trigger npm publish
## Common Tasks
### Clean Everything
```bash
# Clean all build artifacts and caches
pnpm run clean
# Clean storage only
pnpm run clean:storage
```
### Start Production Server
```bash
# Start the CLI (requires build first)
pnpm start
```
### Working with Turbo
Turbo commands run tasks across all packages:
```bash
pnpm run repo:build # Build all packages with Turbo
pnpm run repo:test # Test all packages with Turbo
pnpm run repo:lint # Lint all packages with Turbo
pnpm run repo:typecheck # Typecheck all packages with Turbo
```
## Troubleshooting
### Native Dependencies
If you see errors about missing bindings (e.g., better-sqlite3):
```bash
# Reinstall dependencies
pnpm install
# If that doesn't work, clean and reinstall
pnpm run clean
pnpm install
```
### Port Conflicts
Default ports:
- API/Server: 3001
- WebUI Dev: 3000
Set environment variables to use different ports:
```bash
PORT=4000 API_PORT=4001 pnpm run dev
```
### Global Command Not Found
If `dexto` command is not found after linking:
```bash
# Check global installations
pnpm list -g
npm list -g dexto --depth=0
# Verify PATH includes pnpm/npm global bin
echo $PATH
```
## Questions?
- Check [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution guidelines
- Open an issue for bugs or feature requests
- Join our Discord for development discussions

86
dexto/Dockerfile Normal file
View File

@@ -0,0 +1,86 @@
################################################################################
# Build stage - includes dev dependencies
ARG NODE_VERSION=20.18.1
################################################################################
# Build stage - pnpm workspace build and prune
FROM node:${NODE_VERSION}-alpine AS builder
# Install build dependencies for native modules
RUN apk add --no-cache \
python3 \
make \
g++ \
&& rm -rf /var/cache/apk/*
WORKDIR /app
# Install a pinned pnpm globally (avoid Corepack signature issues in containers)
ARG PNPM_VERSION=10.12.4
RUN npm i -g pnpm@${PNPM_VERSION}
# Copy workspace manifests for better layer caching
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
COPY packages/cli/package.json packages/cli/package.json
COPY packages/core/package.json packages/core/package.json
COPY packages/webui/package.json packages/webui/package.json
# Install workspace dependencies (with lockfile)
RUN pnpm install --frozen-lockfile
# Copy sources and build all packages (embeds WebUI into CLI dist)
COPY . .
RUN pnpm -w build
# Prune to production dependencies
# Prune to production dependencies at the workspace root
# (keeps per-package node_modules; smaller image without dev deps)
RUN pnpm prune --prod
################################################################################
# Production stage - minimal Alpine with Chromium
FROM node:${NODE_VERSION}-alpine AS production
# Install Chromium runtime
RUN apk add --no-cache \
chromium \
&& rm -rf /var/cache/apk/* /tmp/*
WORKDIR /app
# Create non-root user and data dir
RUN addgroup -g 1001 -S dexto && adduser -S dexto -u 1001 \
&& mkdir -p /app/.dexto/database && chown -R dexto:dexto /app/.dexto
# Copy only what we need for runtime
COPY --from=builder --chown=dexto:dexto /app/node_modules ./node_modules
COPY --from=builder --chown=dexto:dexto /app/packages/cli/node_modules ./packages/cli/node_modules
COPY --from=builder --chown=dexto:dexto /app/packages/cli/dist ./packages/cli/dist
COPY --from=builder --chown=dexto:dexto /app/packages/cli/package.json ./packages/cli/package.json
# Copy core workspace package since pnpm links it via node_modules
COPY --from=builder --chown=dexto:dexto /app/packages/core/package.json ./packages/core/package.json
COPY --from=builder --chown=dexto:dexto /app/packages/core/dist ./packages/core/dist
COPY --from=builder --chown=dexto:dexto /app/packages/core/node_modules ./packages/core/node_modules
COPY --from=builder --chown=dexto:dexto /app/agents ./agents
COPY --from=builder --chown=dexto:dexto /app/package.json ./
# Environment
ENV NODE_ENV=production \
PORT=3001 \
API_PORT=3001 \
CONFIG_FILE=/app/agents/coding-agent/coding-agent.yml \
PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true \
PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
# Run as non-root
USER dexto
# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
CMD node -e "const http=require('http');const port=process.env.API_PORT||process.env.PORT||3001;const req=http.request({host:'localhost',port,path:'/health'},res=>process.exit(res.statusCode===200?0:1));req.on('error',()=>process.exit(1));req.end();"
# Fixed port for metadata (runtime can override via -e API_PORT)
EXPOSE 3001
# Server mode: REST APIs + SSE streaming on single port (no Web UI)
CMD ["sh", "-c", "node packages/cli/dist/index.js --mode server --agent $CONFIG_FILE"]

1
dexto/GEMINI.md Symbolic link
View File

@@ -0,0 +1 @@
AGENTS.md

44
dexto/LICENSE Normal file
View File

@@ -0,0 +1,44 @@
Elastic License 2.0 (ELv2)
**Acceptance**
By using the software, you agree to all of the terms and conditions below.
**Copyright License**
The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject to the limitations and conditions below
**Limitations**
You may not provide the software to third parties as a hosted or managed service, where the service provides users with access to any substantial set of the features or functionality of the software.
You may not move, change, disable, or circumvent the license key functionality in the software, and you may not remove or obscure any functionality in the software that is protected by the license key.
You may not alter, remove, or obscure any licensing, copyright, or other notices of the licensor in the software. Any use of the licensor’s trademarks is subject to applicable law.
**Patents**
The licensor grants you a license, under any patent claims the licensor can license, or becomes able to license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case subject to the limitations and conditions in this license. This license does not cover any patent claims that you cause to be infringed by modifications or additions to the software. If you or your company make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
**Notices**
You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms.
If you modify the software, you must include in any modified copies of the software prominent notices stating that you have modified the software.
**No Other Rights**
These terms do not imply any licenses other than those expressly granted in these terms.
**Termination**
If you use the software in violation of these terms, such use is not licensed, and your licenses will automatically terminate. If the licensor provides you with a notice of your violation, and you cease all violation of this license no later than 30 days after you receive that notice, your licenses will be reinstated retroactively. However, if you violate these terms after such reinstatement, any additional violation of these terms will cause your licenses to terminate automatically and permanently.
**No Liability**
As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.
**Definitions**
The _licensor_ is the entity offering these terms, and the _software_ is the software the licensor makes available under these terms, including any portion of it.
_you_ refers to the individual or entity agreeing to these terms.
_your company_ is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. _control_ means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
_your licenses_ are all the licenses granted to you for the software under these terms.
_use_ means anything you do with the software requiring one of your licenses.
_trademark_ means trademarks, service marks, and similar rights.

104
dexto/README.Docker.md Normal file
View File

@@ -0,0 +1,104 @@
# Running Dexto with Docker
This image runs the Dexto CLI in server mode (API + SSE streaming). It uses pnpm workspaces and builds from the current repo (no published packages required).
## Build the image
```bash
docker build -t dexto:local .
```
## Provide configuration and API keys
Create a `.env` file with your keys (see `README.md`):
```ini
OPENAI_API_KEY=...
# add other provider keys as needed
```
The coding agent config is baked into the image at `/app/agents/coding-agent/coding-agent.yml`. You can mount your own agents folder if desired.
## Run: API server only (default)
```bash
docker run --rm \
--env-file .env \
-e API_PORT=3001 \
-p 3001:3001 \
dexto:local
```
What it does:
- Starts REST + SSE streaming server on `API_PORT` (default 3001)
- Uses Chromium inside the image for Puppeteer tools
- Stores runtime data under `/app/.dexto` (in‑container)
Endpoints:
- API base: `http://localhost:3001/api/`
- Health: `http://localhost:3001/health`
- MCP servers: `http://localhost:3001/api/mcp/servers`
Persist data between runs (recommended):
```bash
docker run --rm \
--env-file .env \
-e API_PORT=3001 \
-p 3001:3001 \
-v dexto_data:/app/.dexto \
dexto:local
```
Use a custom agent config:
```bash
docker run --rm \
--env-file .env \
-e API_PORT=3001 \
-e CONFIG_FILE=/app/agents/my-agent.yml \
-v $(pwd)/agents:/app/agents:ro \
-p 3001:3001 \
dexto:local
```
## Run with WebUI (optional)
The image embeds the built WebUI. To run the WebUI alongside the API, start the CLI in `web` mode. This requires two ports (frontend and API):
```bash
docker run --rm \
--env-file .env \
-e FRONTEND_PORT=3000 \
-e API_PORT=3001 \
-p 3000:3000 -p 3001:3001 \
dexto:local \
sh -c "node packages/cli/dist/index.js --mode web --agent $CONFIG_FILE"
```
Open the WebUI: `http://localhost:3000` (the UI calls the API on `http://localhost:3001`).
## Docker Compose (example)
```yaml
services:
dexto:
image: dexto:local
build: .
environment:
API_PORT: 3001
ports:
- "3001:3001"
volumes:
- dexto_data:/app/.dexto
- ./agents:/app/agents:ro
env_file: .env
volumes:
dexto_data: {}
```
## Notes
- Healthcheck uses `API_PORT` (falls back to `PORT` or 3001).
- The container runs as a non‑root user (`dexto`).
- The image builds from your repo code; no published `@dexto/core` is required.

672
dexto/README.md Normal file
View File

@@ -0,0 +1,672 @@
<a href="https://dexto.ai">
<div align="center">
<picture>
<source media="(prefers-color-scheme: light)" srcset=".github/assets/dexto_logo_light.svg">
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/dexto_logo_dark.svg">
<img alt="Dexto" src=".github/assets/dexto_logo_dark.svg" width="55%" style="max-width: 1000px; padding: 48px 8px;">
</picture>
</div>
</a>
<p align="center">
<img src="https://img.shields.io/badge/Status-Beta-yellow">
<img src="https://img.shields.io/badge/License-Elastic%202.0-blue.svg">
<a href="https://discord.gg/GFzWFAAZcm"><img src="https://img.shields.io/badge/Discord-Join%20Chat-7289da?logo=discord&logoColor=white"></a>
<a href="https://deepwiki.com/truffle-ai/dexto"><img src="https://deepwiki.com/badge.svg"></a>
</p>
<!-- Keep these links. Translations will automatically update with the README. -->
<p align="center">
<a href="https://zdoc.app/de/truffle-ai/dexto">Deutsch</a> |
<a href="https://zdoc.app/en/truffle-ai/dexto">English</a> |
<a href="https://zdoc.app/es/truffle-ai/dexto">Español</a> |
<a href="https://zdoc.app/fr/truffle-ai/dexto">français</a> |
<a href="https://zdoc.app/ja/truffle-ai/dexto">日本語</a> |
<a href="https://zdoc.app/ko/truffle-ai/dexto">한국어</a> |
<a href="https://zdoc.app/pt/truffle-ai/dexto">Português</a> |
<a href="https://zdoc.app/ru/truffle-ai/dexto">Русский</a> |
<a href="https://zdoc.app/zh/truffle-ai/dexto">中文</a>
</p>
<p align="center"><b>An open agent harness for AI applications—ships with a powerful coding agent.</b></p>
<div align="center">
<img src=".github/assets/dexto_title.gif" alt="Dexto Demo" width="600" />
</div>
---
## What is Dexto?
Dexto is an **agent harness**—the orchestration layer that turns LLMs into reliable, stateful agents that can take actions, remember context, and recover from errors.
Think of it like an operating system for AI agents:
| Component | Analogy | Role |
|-----------|---------|------|
| **LLM** | CPU | Raw processing power |
| **Context Window** | RAM | Working memory |
| **Dexto** | Operating System | Orchestration, state, tools, recovery |
| **Your Agent** | Application | Domain-specific logic and clients |
### Why Dexto?
- **Configuration-driven**: Define agents in YAML. Swap models and tools without touching code.
- **Batteries included**: Session management, tool orchestration, memory, multimodal support, and observability—out of the box.
- **Run anywhere**: Local, cloud, or hybrid. CLI, Web UI, REST API, Discord, Telegram, or embedded in your app.
### What You Can Build
- **Coding Agents** – Build, debug, and refactor code autonomously
- **Autonomous Agents** – Plan, execute, and adapt to user goals
- **Digital Companions** – Assistants that remember context and anticipate needs
- **MCP Clients & Servers** – Connect tools, files, APIs via Model Context Protocol
- **Multi-Agent Systems** – Agents that collaborate, delegate, and solve complex tasks together
---
## Coding Agent
Dexto ships with a **production-ready coding agent** you can use immediately via the CLI or Web UI.
```bash
# Launch the coding agent (default)
dexto
# Or explicitly
dexto --agent coding-agent
```
**What it can do:**
- Build new apps from scratch
- Read, write, and refactor code across your entire codebase
- Execute shell commands and run tests
- Spawn specialized sub-agents for exploration and planning
- Remember context across sessions with persistent memory
- Work with any of 50+ LLMs (swap models mid-conversation)
**Ready-to-use interfaces:**
- **Web UI** – Chat interface with file uploads, syntax highlighting, and MCP tool browser
- **CLI** – Terminal-native with `/commands`, streaming output, and session management
The coding agent is just one example of what you can build. Create your own agents by defining a YAML config—same architecture, your domain.
---
## Quick Start
### Install
```bash
# Install globally via npm
npm install -g dexto
# Or build from source
git clone https://github.com/truffle-ai/dexto.git
cd dexto && pnpm install && pnpm install-cli
```
### Run
```bash
# Start Dexto (launches setup wizard on first run)
dexto
```
**More options:**
```bash
dexto --mode cli # Terminal mode
dexto -p "create a landing page for a coffee shop" # One-shot task
dexto --auto-approve "refactor this codebase" # Skip confirmations
dexto -m claude-sonnet-4-5-20250929 # Switch models
dexto --help # Explore all options
```
**Inside the interactive CLI**, type `/` to explore commands—switch models, manage sessions, configure tools, and more.
### Manage Settings
```bash
# Configure defaults like LLM provider/model, API keys, or download local models
dexto setup
```
Logs are stored in `~/.dexto/logs/`. Use `DEXTO_LOG_LEVEL=debug` for verbose output.
---
## Core Features
### 50+ LLMs, Instant Switching
Switch models mid-conversation—no code changes, no restarts.
| Provider | Models |
|----------|--------|
| **OpenAI** | gpt-5.2, gpt-5.2-pro, gpt-5.2-codex, o4-mini |
| **Anthropic** | Claude Sonnet, Opus, Haiku (with extended thinking) |
| **Google** | Gemini 3 Pro, 2.5 Pro/Flash |
| **Groq** | Llama 4, Qwen, DeepSeek |
| **xAI** | Grok 4, Grok 3 |
| **Local** | Ollama, GGUF via node-llama-cpp (Llama, Qwen, Mistral, etc.) |
| **+ Gateways** | OpenRouter, AWS Bedrock, Vertex AI, LiteLLM |
**Run locally for privacy**: Local models keep data on your machine with automatic GPU detection (Metal, CUDA, Vulkan).
### MCP Integration (30+ Tools)
Connect to Model Context Protocol servers—Puppeteer, Linear, ElevenLabs, Firecrawl, Sora, and more.
```yaml
# agents/my-agent.yml
mcpServers:
filesystem:
type: stdio
command: npx
args: ['-y', '@modelcontextprotocol/server-filesystem', '.']
browser:
type: stdio
command: npx
args: ['-y', '@anthropics/mcp-server-puppeteer']
```
Browse and add servers from the MCP Store in the Web UI or via `/mcp` commands in the CLI.
### Human-in-the-Loop Controls
Fine-grained control over what your agent can do:
```yaml
toolConfirmation:
mode: manual # Require approval for each tool
# mode: auto-approve # Trust mode for local development
toolPolicies:
alwaysAllow:
- mcp--filesystem--read_file
- mcp--filesystem--list_directory
alwaysDeny:
- mcp--filesystem--delete_file
```
Agents remember which tools you've approved per session.
### Persistent Sessions & Memory
Conversations persist across restarts. Create memories that shape agent behavior.
```bash
# Continue last conversation
dexto -c
# Resume specific session
dexto -r session-abc123
# Search across all conversations
dexto search "database schema"
```
### Multi-Agent Systems
Agents can spawn specialized sub-agents to handle complex subtasks. The coding agent uses this to delegate exploration:
```yaml
# In your agent config
customTools:
- type: agent-spawner
allowedAgents: ["explore-agent"]
maxConcurrentAgents: 5
defaultTimeout: 300000 # 5 minutes
```
**Built-in sub-agents:**
- **explore-agent** – Fast, read-only codebase exploration
Any agent in the [Agent Registry](#agent-registry) can be spawned as a sub-agent—including custom agents you create and register.
Sub-agents run ephemerally, auto-cleanup after completion, and forward tool approvals to the parent—so users see one unified approval flow.
---
## Run Modes
| Mode | Command | Use Case |
|------|---------|----------|
| **Web UI** | `dexto` | Chat interface with file uploads (default) |
| **CLI** | `dexto --mode cli` | Terminal interaction |
| **Web Server** | `dexto --mode server` | REST & SSE APIs |
| **MCP Server** | `dexto --mode mcp` | Expose agent as an MCP server over stdio |
Platform integrations: [Discord](examples/discord-bot/), [Telegram](examples/telegram-bot/)
<details>
<summary><strong>Dexto as an MCP Server</strong></summary>
**Transport: `stdio`**
Connect your Dexto agent as an MCP server in Claude Code or Cursor:
```bash
dexto --mode mcp --auto-approve --no-elicitation # Default agent
dexto --mode mcp --agent coding-agent --auto-approve --no-elicitation
npx dexto --mode mcp --agent coding-agent --auto-approve --no-elicitation
```
Example MCP config for Claude Code or Cursor:
```json
{
"command": "npx",
"args": ["-y", "dexto", "--mode", "mcp", "--agent", "coding-agent", "--auto-approve", "--no-elicitation"]
}
```
`--auto-approve` and `--no-elicitation` are required for MCP mode since it runs non-interactively.
**Transport: `http/sse`**
`dexto --mode server` exposes your agent as an MCP server at `/mcp` for remote clients:
```bash
dexto --mode server --port 3001
ngrok http 3001 # Optional: expose publicly
```
</details>
---
## Dexto Agents SDK
Build AI agents programmatically. Everything the CLI does, your code can too.
```bash
npm install @dexto/core
```
```typescript
import { DextoAgent } from '@dexto/core';
const agent = new DextoAgent({
llm: { provider: 'openai', model: 'gpt-5.2', apiKey: process.env.OPENAI_API_KEY }
});
await agent.start();
const session = await agent.createSession();
const response = await agent.generate('What is TypeScript?', session.id);
console.log(response.content);
// Streaming
for await (const event of await agent.stream('Write a story', session.id)) {
if (event.name === 'llm:chunk') process.stdout.write(event.content);
}
// Multimodal
await agent.generate([
{ type: 'text', text: 'Describe this image' },
{ type: 'image', image: base64Data, mimeType: 'image/png' }
], session.id);
// Switch models mid-conversation
await agent.switchLLM({ model: 'claude-sonnet-4-5-20250929' });
```
**Start a server programmatically:**
Start a Dexto server programmatically to expose REST and SSE streaming APIs to interact and manage your agent backend.
```typescript
import { DextoAgent } from '@dexto/core';
import { loadAgentConfig, startHonoApiServer } from 'dexto';
const config = await loadAgentConfig('./agents/my-agent.yml');
const agent = new DextoAgent(config);
const { server } = await startHonoApiServer(agent, 3001);
// POST /api/message, GET /api/sessions, etc.
```
This starts an HTTP server with full REST and SSE APIs, enabling integration with web frontends, webhooks, and other services. See the [REST API Documentation](https://docs.dexto.ai/api/rest/) for available endpoints.
<details>
<summary><strong>Advanced SDK Usage</strong></summary>
### Session Management
Create and manage multiple conversation sessions with persistent storage.
```typescript
const agent = new DextoAgent(config);
await agent.start();
// Create and manage sessions
const session = await agent.createSession('user-123');
await agent.generate('Hello, how can you help me?', session.id);
// List and manage sessions
const sessions = await agent.listSessions();
const history = await agent.getSessionHistory('user-123');
await agent.deleteSession('user-123');
// Search across conversations
const results = await agent.searchMessages('bug fix', { limit: 10 });
```
### LLM Management
Switch between models and providers dynamically.
```typescript
// Get current configuration
const currentLLM = agent.getCurrentLLMConfig();
// Switch models (provider inferred automatically)
await agent.switchLLM({ model: 'gpt-5.2' });
await agent.switchLLM({ model: 'claude-sonnet-4-5-20250929' });
// Switch model for a specific session
await agent.switchLLM({ model: 'gpt-5.2' }, 'session-123');
// Get supported providers and models
const providers = agent.getSupportedProviders();
const models = agent.getSupportedModels();
```
### MCP Manager
For advanced MCP server management, use the MCPManager directly.
```typescript
import { MCPManager } from '@dexto/core';
const manager = new MCPManager();
// Connect to MCP servers
await manager.connectServer('filesystem', {
type: 'stdio',
command: 'npx',
args: ['-y', '@modelcontextprotocol/server-filesystem', '.']
});
// Access tools, prompts, and resources
const tools = await manager.getAllTools();
const prompts = await manager.getAllPrompts();
const resources = await manager.getAllResources();
// Execute tools
const result = await manager.executeTool('readFile', { path: './README.md' });
await manager.disconnectAll();
```
### Storage & Persistence
Configure storage backends for production.
```yaml
# agents/production-agent.yml
storage:
cache:
type: redis
url: $REDIS_URL
database:
type: postgres
connectionString: $POSTGRES_CONNECTION_STRING
sessions:
maxSessions: 1000
sessionTTL: 86400000 # 24 hours
```
**Supported Backends:**
- **Cache**: Redis, In-Memory
- **Database**: PostgreSQL, SQLite, In-Memory
See the [Storage Configuration guide](https://docs.dexto.ai/docs/guides/configuring-dexto/storage) for details.
</details>
---
## Agent Registry
Pre-built agents for common use cases:
```bash
# List available agents
dexto list-agents
# Install and run
dexto install coding-agent podcast-agent
dexto --agent coding-agent
```
**Available:** Coding, Podcast, Image Editor, Video (Sora), Database, GitHub, Triage (multi-agent), and more.
See the full [Agent Registry](https://docs.dexto.ai/docs/guides/agent-registry).
---
## Agent Configuration
Dexto treats each configuration as a unique agent allowing you to define and save combinations of LLMs, servers, storage options, etc. based on your needs for easy portability. Define agents in version-controlled YAML. Change the file, reload, and chat—state, memory, and tools update automatically.
```yaml
# agents/production-agent.yml
llm:
provider: anthropic
model: claude-sonnet-4-5-20250929
apiKey: $ANTHROPIC_API_KEY
mcpServers:
filesystem:
type: stdio
command: npx
args: ['-y', '@modelcontextprotocol/server-filesystem', '.']
systemPrompt: |
You are a helpful assistant with filesystem access.
storage:
cache:
type: redis
url: $REDIS_URL
database:
type: postgres
connectionString: $POSTGRES_CONNECTION_STRING
toolConfirmation:
mode: manual
```
### LLM Providers
Switch between providers instantly—no code changes required.
#### Built-in Providers
| Provider | Models | Setup |
|----------|--------|-------|
| **OpenAI** | `gpt-5.2`, `gpt-5.2-pro`, `gpt-5.2-codex`, `o4-mini` | API key |
| **Anthropic** | `claude-sonnet-4-5-20250929`, `claude-opus-4-5-20250929`, extended thinking | API key |
| **Google** | `gemini-3-pro`, `gemini-2.5-pro`, `gemini-2.5-flash` | API key |
| **Groq** | `llama-4-scout`, `qwen-qwq`, `deepseek-r1-distill` | API key |
| **xAI** | `grok-4`, `grok-3`, `grok-3-fast` | API key |
| **Cohere** | `command-r-plus`, `command-r` | API key |
#### Local Models (Privacy-First)
| Provider | Models | Setup |
|----------|--------|-------|
| **Ollama** | Llama, Qwen, Mistral, DeepSeek, etc. | Local install |
| **node-llama-cpp** | Any GGUF model | Bundled (auto GPU detection: Metal, CUDA, Vulkan) |
#### Cloud Platforms
| Provider | Models | Setup |
|----------|--------|-------|
| **AWS Bedrock** | Claude, Llama, Mistral | AWS credentials |
| **Google Vertex AI** | Gemini, Claude | GCP credentials |
#### Gateway Providers
| Provider | Access | Setup |
|----------|--------|-------|
| **OpenRouter** | 100+ models from multiple providers | API key |
| **LiteLLM** | Unified API for any provider | Self-hosted or API key |
| **Glama** | Multi-provider gateway | API key |
```bash
# Switch models via CLI
dexto -m claude-sonnet-4-5-20250929
dexto -m gemini-2.5-pro
dexto -m llama-4-scout
```
Switch within interactive CLI (`/model`) or Web UI without config changes.
See the [Configuration Guide](https://docs.dexto.ai/docs/category/agent-configuration-guide).
---
## Demos & Examples
| Image Editor | MCP Store | Portable Agents |
|:---:|:---:|:---:|
| <img src=".github/assets/image_editor_demo.gif" alt="Image Editor" width="280"/> | <img src=".github/assets/mcp_store_demo.gif" alt="MCP Store" width="280"/> | <img src=".github/assets/portable_agent_demo.gif" alt="Portable Agents" width="280"/> |
| Face detection & annotation using OpenCV | Browse and add MCPs | Use agents in Cursor, Claude Code via MCP|
<details>
<summary><strong>More Examples</strong></summary>
### Coding Agent
Build applications from natural language:
```bash
dexto --agent coding-agent
# "Create a snake game and open it in the browser"
```
<img src=".github/assets/coding_agent_demo.gif" alt="Coding Agent Demo" width="600"/>
### Podcast Agent
Generate multi-speaker audio content:
```bash
dexto --agent podcast-agent
```
<img src="https://github.com/user-attachments/assets/cfd59751-3daa-4ccd-97b2-1b2862c96af1" alt="Podcast Agent Demo" width="600"/>
### Multi-Agent Triage
Coordinate specialized agents:
```bash
dexto --agent triage-agent
```
<img src=".github/assets/triage_agent_demo.gif" alt="Triage Agent Demo" width="600">
### Memory System
Persistent context that shapes behavior:
<img src=".github/assets/memory_demo.gif" alt="Memory Demo" width="600">
### Dynamic Forms
Agents generate forms for structured input:
<img src=".github/assets/user_form_demo.gif" alt="User Form Demo" width="600">
### Browser Automation
<a href="https://youtu.be/C-Z0aVbl4Ik">
<img src="https://github.com/user-attachments/assets/3f5be5e2-7a55-4093-a071-8c52f1a83ba3" alt="Amazon Shopping Demo" width="600"/>
</a>
### MCP Playground
Test tools before deploying:
<img src=".github/assets/playground_demo.gif" alt="Playground Demo" width="600">
</details>
---
<details>
<summary><strong>CLI Reference</strong></summary>
```text
Usage: dexto [options] [command] [prompt...]
Basic Usage:
dexto Start web UI (default)
dexto "query" Run one-shot query
dexto --mode cli Interactive CLI
Session Management:
dexto -c Continue last conversation
dexto -r <id> Resume specific session
Options:
-a, --agent <path> Agent config file or ID
-m, --model <model> LLM model to use
--auto-approve Skip tool confirmations
--no-elicitation Disable elicitation prompts
--mode <mode> web | cli | server | mcp
--port <port> Server port
Commands:
setup Configure global preferences
install <agents...> Install agents from registry
list-agents List available agents
session list|history Manage sessions
search <query> Search conversation history
```
Full reference: `dexto --help`
</details>
---
## Documentation
- **[Quick Start](https://docs.dexto.ai/docs/getting-started/intro/)** – Get running in minutes
- **[Configuration Guide](https://docs.dexto.ai/docs/category/guides/)** – Agents, LLMs, tools
- **[SDK Reference](https://docs.dexto.ai/api/sdk/dexto-agent)** – Programmatic usage
- **[REST API](https://docs.dexto.ai/api/rest/)** – HTTP endpoints
---
## Telemetry
We collect anonymous usage data (no personal/sensitive info) to help improve Dexto. This includes:
- Commands used
- Command execution time
- Error occurrences
- System information (OS, Node version)
- LLM Models used
To opt-out:
Set env variable `DEXTO_ANALYTICS_DISABLED=1`
---
## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md).
---
## Community
Built by [Truffle AI](https://www.trytruffle.ai). Join [Discord](https://discord.gg/GFzWFAAZcm) for support.
If you find Dexto useful, please give us a ⭐ on GitHub—it helps a lot!
[![Twitter Follow](https://img.shields.io/twitter/follow/Dexto?style=social)](https://x.com/intent/user?screen_name=dexto_ai)
[![Twitter Follow](https://img.shields.io/twitter/follow/Rahul?style=social)](https://x.com/intent/user?screen_name=Road_Kill11)
[![Twitter Follow](https://img.shields.io/twitter/follow/Shaunak?style=social)](https://x.com/intent/user?screen_name=shaun5k_)
---
## Contributors
[![Contributors](https://contrib.rocks/image?repo=truffle-ai/dexto)](https://github.com/truffle-ai/dexto/graphs/contributors)
---
## License
Elastic License 2.0. See [LICENSE](LICENSE).

219
dexto/VERSIONING.md Normal file
View File

@@ -0,0 +1,219 @@
# Versioning and Release Process
This document describes the versioning strategy and release process for the Dexto monorepo.
## Overview
Dexto uses a monorepo structure with multiple packages:
- `dexto` (CLI) - Main package published to npm
- `@dexto/core` - Core library published to npm
- `@dexto/webui` - Web UI (private, not published)
We use [Changesets](https://github.com/changesets/changesets) for version management and coordinated releases.
## Versioning Strategy
### Fixed Versioning
The `dexto` and `@dexto/core` packages use **fixed versioning** - they always maintain the same version number. This ensures API compatibility between the CLI and core library.
## Automated Release Process (Recommended)
### 1. Create a Changeset
When you make changes that should trigger a release:
```bash
# Create a changeset describing your changes
pnpm changeset
# Follow the interactive prompts to:
# 1. Select which packages changed
# 2. Choose the version bump type (major/minor/patch)
# 3. Write a summary of changes
```
This creates a markdown file in `.changeset/` describing the changes.
> **Why Manual Changesets?** We require manual changeset creation to ensure developers think carefully about semantic versioning and write meaningful changelog entries for users.
### 2. Commit and Push to PR
```bash
# Add the changeset file
git add .changeset/*.md
git commit -m "chore: add changeset for [your feature]"
git push origin your-branch
```
### 3. Automatic Version and Release
When your PR with changesets is merged to `main`:
1. **Version PR Creation** (`changesets-publish.yml` triggers automatically)
- Collects all pending changesets
- Creates a "Version Packages" PR with:
- Version bumps in package.json files
- Updated CHANGELOG.md files
- Consolidated changesets
2. **Review the Version PR**
- Team reviews the version bumps
- Can be merged immediately or held for batching multiple changes
3. **Automatic Publishing** (when Version PR is merged)
- `changesets-publish.yml` triggers
- Builds all packages
- Publishes to npm registry
- Creates git tags
- Removes processed changeset files
### GitHub Workflows
#### Active Release Workflows:
- **[`require-changeset.yml`](.github/workflows/require-changeset.yml)** - Ensures PRs include changesets when needed
- **[`changesets-publish.yml`](.github/workflows/changesets-publish.yml)** - Opens a version bump PR, and publishes it when we merge the version bump PR (triggers on push to main)
#### Quality Check Workflows:
- **[`build_and_test.yml`](.github/workflows/build_and_test.yml)** - Runs tests on PRs
- **[`code-quality.yml`](.github/workflows/code-quality.yml)** - Runs linting and type checking
#### Documentation Workflows:
- **[`build-docs.yml`](.github/workflows/build-docs.yml)** - Builds documentation
- **[`deploy-docs.yml`](.github/workflows/deploy-docs.yml)** - Deploys documentation site
## Manual Release Process (Emergency Only)
If automated release fails or for emergency patches:
### Prerequisites
```bash
# Ensure you're on main and up to date
git checkout main
git pull origin main
# Install dependencies
pnpm install --frozen-lockfile
# Run all quality checks
pnpm run build
pnpm run lint
pnpm run typecheck
pnpm test
```
### Option 1: Manual Changeset Release
```bash
# 1. Create changeset manually
pnpm changeset
# 2. Version packages
pnpm changeset version
# 3. Commit version changes
git add -A
git commit -m "chore: version packages"
# 4. Build all packages
pnpm run build
# 5. Publish to npm
pnpm changeset publish
# 6. Push changes and tags
git push --follow-tags
```
### Option 2: Direct Version Bump (Not Recommended)
```bash
# 1. Update versions manually in package.json files
# IMPORTANT: Keep dexto and @dexto/core versions in sync!
# Edit packages/cli/package.json
# Edit packages/core/package.json
# 2. Install to update lockfile
pnpm install
# 3. Build packages
pnpm run build
# 4. Create git tag
git add -A
git commit -m "chore: release v1.2.0"
git tag v1.2.0
# 5. Publish packages
cd packages/core && pnpm publish --access public
cd ../cli && pnpm publish --access public
# 6. Push commits and tags
git push origin main --follow-tags
```
## Testing Releases (Without Publishing)
### Dry Run Commands
```bash
# See what would be published
pnpm publish -r --dry-run --no-git-checks
# Check changeset status
pnpm changeset status
# Preview version changes
pnpm changeset version --dry-run
# Test package contents
cd packages/cli && npm pack --dry-run
cd packages/core && npm pack --dry-run
```
### Local Testing
```bash
# Link packages locally for testing
pnpm run link-cli
# Test the linked CLI
dexto --version
```
## Release Checklist
Before any release:
- [ ] All tests passing (`pnpm test`)
- [ ] No lint errors (`pnpm run lint`)
- [ ] TypeScript compiles (`pnpm run typecheck`)
- [ ] Build succeeds (`pnpm run build`)
- [ ] Changeset created (if using automated flow)
- [ ] Version numbers synchronized (dexto and @dexto/core)
## Common Issues
### Issue: Versions out of sync
**Solution**: Ensure `dexto` and `@dexto/core` have the same version in their package.json files.
### Issue: Publish fails with "Package not found"
**Solution**: Run `pnpm run build` before publishing to ensure dist folders exist.
### Issue: Git working directory not clean
**Solution**: Commit or stash all changes before publishing. Use `--no-git-checks` flag for testing only.
### Issue: Authentication error when publishing
**Solution**: CI uses `NPM_TOKEN` secret (granular access token). Ensure the token is valid and has publish permissions for `@dexto` scope. For local publishing, use `npm login`.
## Version History
See package CHANGELOGs for detailed version history:
- packages/cli/CHANGELOG.md
- packages/core/CHANGELOG.md
## Questions?
For questions about the release process, please open an issue or consult the team.

306
dexto/agents/README.md Normal file
View File

@@ -0,0 +1,306 @@
# Configuration Guide
Dexto uses a YAML configuration file to define tool servers and AI settings. This guide provides detailed information on all available configuration options.
## Configuration File Location
By default, Dexto looks for a configuration file at `agents/coding-agent/coding-agent.yml` in the project directory. You can specify a different location using the `--agent` command-line option:
```bash
npm start -- --agent path/to/your/agent.yml
```
## Configuration Structure
The configuration file has two main sections:
1. `mcpServers`: Defines the tool servers to connect to
2. `llm`: Configures the AI provider settings
### Basic Example
```yaml
mcpServers:
github:
type: stdio
command: npx
args:
- -y
- "@modelcontextprotocol/server-github"
env:
GITHUB_PERSONAL_ACCESS_TOKEN: your-github-token
filesystem:
type: stdio
command: npx
args:
- -y
- "@modelcontextprotocol/server-filesystem"
- .
llm:
provider: openai
model: gpt-5
apiKey: $OPENAI_API_KEY
```
## Tool Server Configuration
Each entry under `mcpServers` defines a tool server to connect to. The key (e.g., "github", "filesystem") is used as a friendly name for the server.
Tool servers can either be local servers (stdio) or remote servers (sse)
### Stdio Server Options
| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `type` | string | Yes | The type of the server, needs to be 'stdio' |
| `command` | string | Yes | The executable to run |
| `args` | string[] | No | Array of command-line arguments |
| `env` | object | No | Environment variables for the server process |
### SSE Server Options
| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `type` | string | Yes | The type of the server, needs to be 'sse' |
| `url` | string | Yes | The url of the server |
| `headers` | map | No | Optional headers for the url |
## LLM Configuration
The `llm` section configures the AI provider settings.
### LLM Options
| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `provider` | string | Yes | AI provider (e.g., "openai", "anthropic", "google") |
| `model` | string | Yes | The model to use |
| `apiKey` | string | Yes | API key or environment variable reference |
| `temperature` | number | No | Controls randomness (0-1, default varies by provider) |
| `maxInputTokens` | number | No | Maximum input tokens for context compression |
| `maxOutputTokens` | number | No | Maximum output tokens for response length |
| `baseURL` | string | No | Custom API endpoint for OpenAI-compatible providers |
### API Key Configuration
#### Setting API Keys
API keys can be configured in two ways:
1. **Environment Variables (Recommended)**:
- Add keys to your `.env` file (use `.env.example` as a template) or export environment variables
- Reference them in config with the `$` prefix
2. **Direct Configuration** (Not recommended for security):
- Directly in the YAML file (less secure, avoid in production)
```yaml
# Recommended: Reference environment variables
apiKey: $OPENAI_API_KEY
# Not recommended: Direct API key in config
apiKey: sk-actual-api-key
```
#### Security Best Practices
- Never commit API keys to version control
- Use environment variables in production environments
- Create a `.gitignore` entry for your `.env` file
#### API Keys for Different Providers
Each provider requires its own API key:
- OpenAI: Set `OPENAI_API_KEY` in `.env`
- Anthropic: Set `ANTHROPIC_API_KEY` in `.env`
- Google Gemini: Set `GOOGLE_GENERATIVE_AI_API_KEY` in `.env`
#### Openai example
```yaml
llm:
provider: openai
model: gpt-5
apiKey: $OPENAI_API_KEY
```
#### Anthropic example
```yaml
llm:
provider: anthropic
model: claude-sonnet-4-5-20250929
apiKey: $ANTHROPIC_API_KEY
```
#### Google example
```yaml
llm:
provider: google
model: gemini-2.0-flash
apiKey: $GOOGLE_GENERATIVE_AI_API_KEY
```
## Optional Greeting
Add a simple `greeting` at the root of your config to provide a default welcome text that UI layers can display when a chat starts:
```yaml
greeting: "Hi! I’m Dexto — how can I help today?"
```
### Windows Support
On Windows systems, some commands like `npx` may have different paths. The system attempts to automatically detect and uses the correct paths for these commands on Windows. If you run into any issues during server initialization, you may need to adjust the path to your `npx` command.
## Supported Tool Servers
Here are some commonly used MCP-compatible tool servers:
### GitHub
```yaml
github:
type: stdio
command: npx
args:
- -y
- "@modelcontextprotocol/server-github"
env:
GITHUB_PERSONAL_ACCESS_TOKEN: your-github-token
```
### Filesystem
```yaml
filesystem:
type: stdio
command: npx
args:
- -y
- "@modelcontextprotocol/server-filesystem"
- .
```
### Terminal
```yaml
terminal:
type: stdio
command: npx
args:
- -y
- "@modelcontextprotocol/server-terminal"
```
### Desktop Commander
```yaml
desktop:
type: stdio
command: npx
args:
- -y
- "@wonderwhy-er/desktop-commander"
```
### Custom Server
```yaml
custom:
type: stdio
command: node
args:
- --loader
- ts-node/esm
- src/servers/customServer.ts
env:
API_KEY: your-api-key
```
### Remote Server
This example uses a remote github server provided by composio.
The URL is just a placeholder which won't work out of the box since the URL is customized per user.
Go to mcp.composio.dev to get your own MCP server URL.
```yaml
github-remote:
type: sse
url: https://mcp.composio.dev/github/repulsive-itchy-alarm-ABCDE
```
## Command-Line Options
Dexto supports several command-line options:
| Option | Description |
|--------|-------------|
| `--agent` | Specify a custom agent configuration file |
| `--strict` | Require all connections to succeed |
| `--verbose` | Enable verbose logging |
| `--help` | Show help |
## Available Agent Examples
### Database Agent
An AI agent that provides natural language access to database operations and analytics. This approach simplifies database interaction - instead of building forms, queries, and reporting dashboards, users can simply ask for what they need in plain language.
**Quick Start:**
```bash
cd database-agent
./setup-database.sh
npm start -- --agent database-agent.yml
```
**Example Interactions:**
- "Show me all users"
- "Create a new user named John Doe with email john@example.com"
- "Find products under $100"
- "Generate a sales report by category"
This agent demonstrates intelligent database interaction through conversation.
## Complete Example
Here's a comprehensive configuration example using multiple tool servers:
```yaml
mcpServers:
github:
type: stdio
command: npx
args:
- -y
- "@modelcontextprotocol/server-github"
env:
GITHUB_PERSONAL_ACCESS_TOKEN: your-github-token
filesystem:
type: stdio
command: npx
args:
- -y
- "@modelcontextprotocol/server-filesystem"
- .
terminal:
type: stdio
command: npx
args:
- -y
- "@modelcontextprotocol/server-terminal"
desktop:
type: stdio
command: npx
args:
- -y
- "@wonderwhy-er/desktop-commander"
custom:
type: stdio
command: node
args:
- --loader
- ts-node/esm
- src/servers/customServer.ts
env:
API_KEY: your-api-key
llm:
provider: openai
model: gpt-5
apiKey: $OPENAI_API_KEY
```

148
dexto/agents/agent-registry.json Normal file
View File

@@ -0,0 +1,148 @@
{
"version": "1.0.0",
"agents": {
"database-agent": {
"id": "database-agent",
"name": "Database Agent",
"description": "AI agent for database operations and SQL queries",
"author": "Truffle AI",
"tags": ["database", "sql", "data", "queries"],
"source": "database-agent/",
"main": "database-agent.yml"
},
"github-agent": {
"id": "github-agent",
"name": "GitHub Agent",
"description": "GitHub operations agent for analyzing pull requests, issues, repos and more",
"author": "Truffle AI",
"tags": ["github", "repositories", "collaboration", "devops", "mcp"],
"source": "github-agent/",
"main": "github-agent.yml"
},
"talk2pdf-agent": {
"id": "talk2pdf-agent",
"name": "Talk2PDF Agent",
"description": "PDF document analysis and conversation",
"author": "Truffle AI",
"tags": ["pdf", "documents", "analysis", "conversation"],
"source": "talk2pdf-agent/",
"main": "talk2pdf-agent.yml"
},
"image-editor-agent": {
"id": "image-editor-agent",
"name": "Image Editor Agent",
"description": "AI agent for image editing and manipulation",
"author": "Truffle AI",
"tags": ["images", "editing", "graphics", "visual"],
"source": "image-editor-agent/",
"main": "image-editor-agent.yml"
},
"music-agent": {
"id": "music-agent",
"name": "Music Agent",
"description": "AI agent for music creation and audio processing",
"author": "Truffle AI",
"tags": ["music", "audio", "creation", "sound"],
"source": "music-agent/",
"main": "music-agent.yml"
},
"product-researcher": {
"id": "product-researcher",
"name": "Product Researcher",
"description": "AI agent for product name research and branding",
"author": "Truffle AI",
"tags": ["product", "research", "branding", "naming"],
"source": "product-name-researcher/",
"main": "product-name-researcher.yml"
},
"triage-agent": {
"id": "triage-agent",
"name": "Triage Agent",
"description": "Customer support triage system",
"author": "Truffle AI",
"tags": ["support", "triage", "routing", "multi-agent"],
"source": "triage-demo/",
"main": "triage-agent.yml"
},
"nano-banana-agent": {
"id": "nano-banana-agent",
"name": "Nano Banana Agent",
"description": "AI agent for advanced image generation and editing using Google's Nano Banana (Gemini 2.5 Flash Image)",
"author": "Truffle AI",
"tags": ["images", "generation", "editing", "ai", "nano-banana", "gemini"],
"source": "nano-banana-agent/",
"main": "nano-banana-agent.yml"
},
"podcast-agent": {
"id": "podcast-agent",
"name": "Podcast Agent",
"description": "Advanced podcast generation agent using Google Gemini TTS for multi-speaker audio content",
"author": "Truffle AI",
"tags": ["podcast", "audio", "tts", "speech", "multi-speaker", "gemini"],
"source": "podcast-agent/",
"main": "podcast-agent.yml"
},
"sora-video-agent": {
"id": "sora-video-agent",
"name": "Sora Video Agent",
"description": "AI agent for video generation using OpenAI's Sora technology with comprehensive video creation and management capabilities",
"author": "Truffle AI",
"tags": ["video", "generation", "sora", "openai", "ai", "media", "creation"],
"source": "sora-video-agent/",
"main": "sora-video-agent.yml"
},
"default-agent": {
"id": "default-agent",
"name": "Default",
"description": "Default Dexto agent with filesystem and playwright tools",
"author": "Truffle AI",
"tags": ["default", "filesystem", "playwright"],
"source": "default-agent.yml"
},
"coding-agent": {
"id": "coding-agent",
"name": "Coding Agent",
"description": "Expert software development assistant with all internal coding tools for building, debugging, and maintaining codebases",
"author": "Truffle AI",
"tags": ["coding", "development", "software", "internal-tools", "programming"],
"source": "coding-agent/",
"main": "coding-agent.yml"
},
"workflow-builder-agent": {
"id": "workflow-builder-agent",
"name": "Workflow Builder Agent",
"description": "AI agent for building and managing n8n automation workflows with comprehensive workflow, execution, and credential management",
"author": "Truffle AI",
"tags": ["n8n", "automation", "workflows", "integration", "mcp"],
"source": "workflow-builder-agent/",
"main": "workflow-builder-agent.yml"
},
"product-analysis-agent": {
"id": "product-analysis-agent",
"name": "Product Analysis Agent",
"description": "AI agent for product analytics using PostHog with insights, feature flags, error tracking, and user behavior analysis",
"author": "Truffle AI",
"tags": ["posthog", "analytics", "product", "insights", "feature-flags", "mcp"],
"source": "product-analysis-agent/",
"main": "product-analysis-agent.yml"
},
"gaming-agent": {
"id": "gaming-agent",
"name": "Gaming Agent",
"description": "AI agent that plays GameBoy games like Pokemon through an emulator with screen capture and button controls",
"author": "Truffle AI",
"tags": ["gaming", "gameboy", "pokemon", "emulator", "mcp"],
"source": "gaming-agent/",
"main": "gaming-agent.yml"
},
"explore-agent": {
"id": "explore-agent",
"name": "Explore Agent",
"description": "Fast, read-only agent for codebase exploration. Use for: 'explore the codebase', 'what's in this folder', 'how does X work', 'find where Y is handled', 'understand the architecture'. Optimized for speed with Haiku.",
"author": "Truffle AI",
"tags": ["explore", "search", "understand", "find", "research"],
"source": "explore-agent/",
"main": "explore-agent.yml"
}
}
}

81
dexto/agents/agent-template.yml Normal file
View File

@@ -0,0 +1,81 @@
# Template for dexto create-app
# describes the mcp servers to use
mcpServers:
filesystem:
type: stdio
command: npx
args:
- -y
- "@modelcontextprotocol/server-filesystem"
- .
playwright:
type: stdio
command: npx
args:
- -y
- "@playwright/mcp@latest"
# System prompt configuration - defines the agent's behavior and instructions
systemPrompt:
contributors:
- id: primary
type: static
priority: 0
content: |
You are a helpful AI assistant with access to tools.
Use these tools when appropriate to answer user queries.
You can use multiple tools in sequence to solve complex problems.
After each tool result, determine if you need more information or can provide a final answer.
- id: date
type: dynamic
priority: 10
source: date
enabled: true
# LLM configuration - describes the language model to use
llm:
provider: openai
model: gpt-5-mini
apiKey: $OPENAI_API_KEY
# Alternative LLM providers (replace the above llm section with one of these):
# Google Gemini:
# llm:
# provider: google
# model: gemini-2.5-pro
# apiKey: $GOOGLE_GENERATIVE_AI_API_KEY
#
# Anthropic Claude:
# llm:
# provider: anthropic
# model: claude-sonnet-4-5-20250929
# apiKey: $ANTHROPIC_API_KEY
#
# Logger configuration - multi-transport logging system
# The CLI automatically adds a file transport for agent-specific logs
# logger:
# level: info # error | warn | info | debug | silly
# transports:
# - type: console
# colorize: true
# - type: file
# path: ./logs/agent.log
# maxSize: 10485760 # 10MB
# maxFiles: 5
# Storage configuration - uses a two-tier architecture: cache (fast, ephemeral) and database (persistent, reliable)
# Memory cache with file-based database (good for development with persistence)
storage:
cache:
type: in-memory
database:
type: sqlite
blob:
type: in-memory
# Tool confirmation configuration - auto-approve for better development experience
toolConfirmation:
mode: auto-approve
# timeout: omitted = infinite wait
allowedToolsStorage: memory

188
dexto/agents/coding-agent/README.md Normal file
View File

@@ -0,0 +1,188 @@
# Coding Agent
An expert software development assistant optimized for building, debugging, and maintaining codebases. This agent comes equipped with all internal coding tools and is configured to handle complex software engineering tasks efficiently.
## What You Get
- **All Internal Coding Tools**: Read, write, edit files, execute commands, search codebases
- **Intelligent Tool Policies**: Read operations never require approval, write operations are safely guarded
- **Comprehensive File Support**: 30+ file extensions including JS/TS, Python, Go, Rust, Java, C/C++, configs, and more
- **Enhanced Codebase Access**: Index up to 500 files with depth-10 traversal, including hidden files
- **Expert System Prompt**: Specialized instructions for software development best practices
- **Persistent Tool Approvals**: Allowed tools are saved across sessions for smoother workflows
- **Coding-Focused Starter Prompts**: Quick access to common development tasks
## Key Capabilities
### File Operations
- **read_file**: Read any file with pagination support
- **write_file**: Create new files (requires approval)
- **edit_file**: Modify existing files precisely (requires approval)
- **glob_files**: Find files using patterns like `**/*.ts` (no approval needed)
- **grep_content**: Search within files using regex (no approval needed)
### Command Execution
- **bash_exec**: Run shell commands for testing, building, running code (requires approval)
- **bash_output**: Monitor output from background processes
- **kill_process**: Terminate running processes
### Analysis & Search
- Deep codebase traversal (up to 10 levels)
- Search across 500+ files
- Pattern matching with glob and regex
- Hidden file access (.env, .gitignore, etc.)
## Requirements
- Node.js 18+ (if using npm/pnpm commands)
- OpenAI API key (or another configured LLM key)
- File system access to your project directory
## Run the Agent
```bash
# From Dexto source
npm start -- --agent agents/coding-agent/coding-agent.yml
# Or using the Dexto CLI
dexto --agent coding-agent
```
## Usage Examples
### Analyze a Codebase
```
"Analyze this codebase. Show me the project structure, main technologies used, and provide a high-level overview."
```
### Debug an Error
```
"I'm getting this error: [paste error]. Help me find and fix the issue."
```
### Implement a Feature
```
"I need to add user authentication. Help me design and implement it following best practices."
```
### Refactor Code
```
"This function is too complex. Help me refactor it for better readability and maintainability."
```
### Write Tests
```
"Generate unit tests for the UserService class with edge case coverage."
```
### Code Review
```
"Review my recent changes in src/auth/ and suggest improvements."
```
## Configuration
### LLM Options
The coding agent defaults to `gpt-4o` for powerful coding capabilities. You can switch to other models:
**Claude Sonnet (Excellent for Coding)**
```yaml
llm:
provider: anthropic
model: claude-sonnet-4-20250514
apiKey: $ANTHROPIC_API_KEY
```
**Google Gemini**
```yaml
llm:
provider: google
model: gemini-2.5-pro
apiKey: $GOOGLE_GENERATIVE_AI_API_KEY
```
**OpenAI o1 (For Complex Reasoning)**
```yaml
llm:
provider: openai
model: o1
apiKey: $OPENAI_API_KEY
```
### Tool Policies
The agent is pre-configured with sensible defaults:
**Always Allowed (No Approval Needed)**
- Reading files (`internal--read_file`)
- Searching files (`internal--glob_files`, `internal--grep_content`)
- Checking process output (`internal--bash_output`)
- Killing processes (`internal--kill_process`)
- Asking questions (`internal--ask_user`)
**Requires Approval**
- Writing files (`internal--write_file`)
- Editing files (`internal--edit_file`)
- Executing commands (`internal--bash_exec`)
You can customize these policies in the `toolConfirmation.toolPolicies` section of `coding-agent.yml`.
### File Extensions
The agent indexes these file types by default:
**Web Development**: .js, .jsx, .ts, .tsx, .html, .css, .scss, .sass, .less, .vue, .svelte
**Backend Languages**: .py, .java, .go, .rs, .rb, .php, .c, .cpp, .h, .hpp, .cs, .swift, .kt
**Configuration**: .json, .yaml, .yml, .toml, .xml, .ini, .env
**Documentation**: .md, .mdx, .txt, .rst
**Build Files**: .gradle, .maven, Makefile, Dockerfile, .dockerignore, .gitignore
Add more extensions in the `internalResources.resources[0].includeExtensions` section.
## Starter Prompts
The agent includes 8 built-in starter prompts:
1. **🔍 Analyze Codebase** - Get a project overview
2. **🐛 Debug Error** - Identify and fix bugs
3. **♻️ Refactor Code** - Improve code quality
4. **🧪 Write Tests** - Generate comprehensive tests
5. **✨ Implement Feature** - Build new functionality
6. **⚡ Optimize Performance** - Find bottlenecks
7. **🚀 Setup Project** - Initialize new projects
8. **👀 Code Review** - Review for issues and improvements
## Best Practices
1. **Read Before Writing**: The agent automatically searches and reads relevant code before making changes
2. **Use Glob & Grep**: Leverage pattern matching to explore unfamiliar codebases efficiently
3. **Test Changes**: Execute tests after modifications to verify correctness
4. **Follow Conventions**: The agent adapts to your project's existing code style
5. **Ask Questions**: The agent will ask for clarification when requirements are ambiguous
## Troubleshooting
### Agent Can't Find Files
- Ensure you're running from your project root
- Check that file extensions are included in the config
- Verify `maxDepth` is sufficient for your project structure
### Commands Require Too Many Approvals
- Use `allowedToolsStorage: storage` to persist approvals
- Add frequently-used commands to the `alwaysAllow` list
### Performance Issues with Large Codebases
- Increase `maxFiles` limit (default: 500)
- Reduce `maxDepth` to limit traversal
- Exclude large directories in `.gitignore`
## Learn More
- [Dexto Documentation](https://github.com/truffle-ai/dexto)
- [Internal Tools Reference](../../docs/internal-tools.md)
- [Agent Configuration Guide](../../docs/agent-configuration.md)

298
dexto/agents/coding-agent/coding-agent.yml Normal file
View File

@@ -0,0 +1,298 @@
# Coding Agent Configuration
# Optimized for software development with internal coding tools
# Image: Specifies the provider bundle for this agent
# This agent requires local development tools (filesystem, process)
image: '@dexto/image-local'
# System prompt configuration - defines the agent's behavior as a coding assistant
systemPrompt:
contributors:
- id: date
type: dynamic
priority: 10
source: date
- id: env
type: dynamic
priority: 15
source: env
- id: primary
type: static
priority: 0
content: |
You are an expert software development assistant with deep knowledge of multiple programming languages,
frameworks, and development best practices.
Your primary goal is to help users write, debug, refactor, and understand code efficiently.
Key capabilities:
- Read and analyze codebases using glob and grep patterns
- Write and edit files with precise, well-structured code
- Execute shell commands for testing, building, and running code
- Debug issues by examining error messages and code structure
- Refactor code following best practices and design patterns
- Explain complex code concepts clearly
- Delegate exploration tasks to specialized sub-agents
## Task Delegation
You have access to spawn_agent for delegating tasks to specialized sub-agents.
**When to delegate to explore-agent:**
- Open-ended exploration: "explore the codebase", "what's in this folder", "how does X work"
- Understanding architecture: "explain the project structure", "how are components organized"
- Finding patterns: "where is authentication handled", "find all API endpoints"
- Research tasks: "what testing framework is used", "how is state managed"
**When to use your own tools directly:**
- Specific file operations: "read src/index.ts", "edit the config file"
- Targeted searches: "find the User class", "grep for 'TODO'"
- Writing/editing code: any task that requires modifications
- Running commands: build, test, install dependencies
**Rule of thumb:** If the task requires understanding or exploring before you know what to do, delegate to explore-agent first. If you know exactly what file/function to target, use your tools directly.
## Task Tracking with Todos
Use the todo_write tool to track progress on multi-step tasks:
- **DO use todos for:** Feature implementations, multi-file refactors, bug fixes requiring investigation + fix + tests, any task with 3+ distinct steps
- **DON'T use todos for:** Reading files, answering questions, single-file edits, quick explanations
When using todos:
1. Create the todo list when you identify a multi-step task
2. Mark a task as in_progress when you start working on it
3. Mark it as completed when done, and move to the next task
4. Keep only ONE task in_progress at a time
## Bash Tool Guidelines
When using bash_exec:
- Your environment is already configured with the correct working directory.
- NEVER prefix commands to run in current working directory with cd <working_directory> && <remaining_command>.
- Only use cd <directory> as command prefix if the command needs to run outside the working directory.
## Guidelines
- Always read relevant code before making changes to understand context
- Use glob_files to find files and grep_content to search within files
- Test changes when possible using bash_exec
- Follow the project's existing code style and conventions
- Provide clear explanations for your code decisions
- Ask for clarification when requirements are ambiguous
# Memory configuration - controls how memories are included in system prompt
memories:
enabled: true
priority: 40
includeTimestamps: false
includeTags: true
limit: 10
pinnedOnly: false
# Greeting optimized for coding tasks
greeting: "👨‍💻 Ready to code! What are we building today?"
# LLM configuration - using a powerful model for coding tasks
llm:
provider: anthropic
model: claude-sonnet-4-5-20250929
apiKey: $ANTHROPIC_API_KEY
storage:
cache:
type: in-memory
database:
type: sqlite
blob:
type: local # CLI provides storePath automatically
maxBlobSize: 52428800 # 50MB per blob
maxTotalSize: 1073741824 # 1GB total storage
cleanupAfterDays: 30
toolConfirmation:
mode: manual
# timeout: omitted = infinite wait (no timeout for CLI)
allowedToolsStorage: storage # Persist allowed tools across sessions
# Tool policies optimized for coding workflows
toolPolicies:
# Tools that never require approval (safe, read-only operations)
# Use qualified names: custom--{tool_id} for custom tools, internal--{tool_id} for internal tools
alwaysAllow:
- internal--ask_user
- custom--read_file # Read files without approval
- custom--glob_files # Search for files without approval
- custom--grep_content # Search within files without approval
- custom--bash_output # Check background process output
- custom--kill_process # Kill processes without approval (only processes started by agent)
- custom--todo_write # Todo updates don't need approval
- custom--plan_read # Read plan without approval
# Tools that are always denied (dangerous operations)
# Uncomment to restrict certain operations
# alwaysDeny:
# - custom--process-tools--bash_exec--rm -rf* # Prevent recursive deletion
# Compaction configuration - automatically summarizes conversation when context is full
compaction:
type: reactive-overflow
enabled: true
# Uncomment to override model's context window (useful for testing or capping usage):
# maxContextTokens: 50000 # Cap at 50K tokens regardless of model's max
# thresholdPercent: 0.9 # Trigger at 90% of context window (leaves safety buffer)
# Elicitation configuration - required for ask_user tool
elicitation:
enabled: true
# timeout: omitted = infinite wait (no timeout for CLI)
# Internal tools - core tools that are always available
internalTools:
- ask_user # Ask questions and collect input
- invoke_skill # Invoke skills/prompts during execution
# Custom tools - filesystem and process tools from image-local
customTools:
- type: filesystem-tools
allowedPaths: ["."]
blockedPaths: [".git", "node_modules/.bin", ".env"]
blockedExtensions: [".exe", ".dll", ".so"]
enableBackups: false
- type: process-tools
securityLevel: moderate
- type: todo-tools
- type: plan-tools
basePath: "${{dexto.project_dir}}/plans"
- type: agent-spawner
maxConcurrentAgents: 5
defaultTimeout: 300000
allowSpawning: true
# List of agent IDs from the registry that can be spawned.
# Agent metadata (name, description) is pulled from the registry at runtime.
allowedAgents:
- explore-agent
# Agents with read-only tools that should have auto-approved tool calls
autoApproveAgents:
- explore-agent
# Internal resources configuration - expanded for coding projects
internalResources:
enabled: true
resources:
# Filesystem resource - comprehensive file access for coding
- type: filesystem
paths: ["."]
maxFiles: 500 # Increased for larger codebases
maxDepth: 10 # Deeper traversal for nested projects
includeHidden: true # Include hidden files (.env, .gitignore, etc.)
includeExtensions:
# Web development
- .js
- .jsx
- .ts
- .tsx
- .html
- .css
- .scss
- .sass
- .less
- .vue
- .svelte
# Backend languages
- .py
- .java
- .go
- .rs
- .rb
- .php
- .c
- .cpp
- .h
- .hpp
- .cs
- .swift
- .kt
# Shell and config
- .sh
- .bash
- .zsh
- .fish
# Config and data
- .json
- .yaml
- .yml
- .toml
- .xml
- .ini
- .env
# Documentation
- .md
- .mdx
- .txt
- .rst
# Build and package files
- .gradle
- .maven
- .dockerignore
- .gitignore
# Blob resource - for handling build artifacts, images, etc.
- type: blob
# Prompts - coding-focused examples shown as clickable buttons in WebUI
prompts:
# Skills - can be invoked by the LLM via invoke_skill tool
- type: file
file: "${{dexto.agent_dir}}/skills/code-review.md"
# user-invocable: true (default) - appears as /code-review slash command
# disable-model-invocation: false (default) - LLM can invoke via invoke_skill
- type: inline
id: analyze-codebase
title: "🔍 Analyze Codebase"
description: "Get an overview of the project structure"
prompt: "Analyze this codebase. Show me the project structure, main technologies used, and provide a high-level overview."
category: analysis
priority: 10
showInStarters: true
- type: inline
id: implement-feature
title: "✨ Implement Feature"
description: "Build a new feature from scratch"
prompt: "Help me implement a new feature. I'll describe what I need, and you can design and implement it following best practices."
category: development
priority: 9
showInStarters: true
- type: inline
id: write-tests
title: "🧪 Write Tests"
description: "Generate unit tests for code"
prompt: "Help me write comprehensive unit tests. Identify the testing framework and create tests that cover edge cases."
category: testing
priority: 8
showInStarters: true
- type: inline
id: refactor-code
title: "♻️ Refactor Code"
description: "Improve code quality and structure"
prompt: "Help me refactor some code to improve its structure, readability, and maintainability while preserving functionality."
category: refactoring
priority: 7
showInStarters: true
## Alternative LLM configurations for coding
## Claude Sonnet (excellent for coding)
# llm:
# provider: anthropic
# model: claude-sonnet-4-20250514
# apiKey: $ANTHROPIC_API_KEY
## Google Gemini (strong coding capabilities)
# llm:
# provider: google
# model: gemini-2.5-pro
# apiKey: $GOOGLE_GENERATIVE_AI_API_KEY
## OpenAI o1 (for complex reasoning tasks)
# llm:
# provider: openai
# model: o1
# apiKey: $OPENAI_API_KEY

46
dexto/agents/coding-agent/skills/code-review.md Normal file
View File

@@ -0,0 +1,46 @@
---
title: Code Review
description: Perform a thorough code review on the specified files or changes
arguments:
- name: focus
description: Optional focus area (security, performance, style, all)
required: false
---
# Code Review Skill
You are now performing a code review. Follow these guidelines:
## Review Checklist
1. **Correctness**: Does the code do what it's supposed to do?
2. **Security**: Are there any security vulnerabilities (injection, XSS, etc.)?
3. **Performance**: Are there any obvious performance issues?
4. **Readability**: Is the code easy to understand?
5. **Maintainability**: Will this code be easy to maintain?
6. **Error Handling**: Are errors handled appropriately?
7. **Tests**: Are there adequate tests for the changes?
## Output Format
Structure your review as:
### Summary
Brief overview of what the code does and overall assessment.
### Issues Found
List any problems, categorized by severity:
- **Critical**: Must fix before merge
- **Major**: Should fix, but not blocking
- **Minor**: Nice to have improvements
- **Nitpick**: Style/preference suggestions
### Positive Highlights
Note any particularly good patterns or practices.
### Recommendations
Actionable suggestions for improvement.
---
Begin the code review now. If no specific files were mentioned, ask the user what they'd like reviewed.

35
dexto/agents/database-agent/README.md Normal file
View File

@@ -0,0 +1,35 @@
# Database Agent
An AI agent that provides natural language access to database operations and analytics. This approach changes how we interact with data - instead of learning SQL syntax, building query interfaces, or designing complex dashboards, users can simply ask for what they need in natural language.
## Setup
```bash
cd database-agent
./setup-database.sh
npm start -- --agent database-agent.yml
```
## Example Interactions
- "Show me all users"
- "Create a new user named John Doe with email john@example.com"
- "Find products under $100"
- "Generate a sales report by category"
## Capabilities
- **Data Queries**: Natural language database queries and reporting
- **Data Management**: Create, update, and delete records
- **Analytics**: Generate insights and business intelligence
- **Schema Operations**: Table creation and database structure management
## How It Works
The agent connects to a SQLite database via MCP server and:
- Interprets natural language requests into SQL queries
- Validates data before operations
- Provides formatted results and insights
- Handles errors gracefully with helpful suggestions
This agent demonstrates intelligent database interaction through conversation.

BIN
dexto/agents/database-agent/data/example.db Normal file
View File

Binary file not shown.

98
dexto/agents/database-agent/database-agent-example.sql Normal file
View File

@@ -0,0 +1,98 @@
-- Sample database schema and data for the Database Interaction Agent
-- This demonstrates the types of operations the agent can perform
-- Create users table
CREATE TABLE IF NOT EXISTS users (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL,
email TEXT UNIQUE NOT NULL,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
last_login DATETIME,
is_active BOOLEAN DEFAULT 1
);
-- Create products table
CREATE TABLE IF NOT EXISTS products (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL,
description TEXT,
price DECIMAL(10,2) NOT NULL,
category TEXT NOT NULL,
stock_quantity INTEGER DEFAULT 0,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
-- Create orders table
CREATE TABLE IF NOT EXISTS orders (
id INTEGER PRIMARY KEY AUTOINCREMENT,
user_id INTEGER NOT NULL,
total_amount DECIMAL(10,2) NOT NULL,
status TEXT DEFAULT 'pending',
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (user_id) REFERENCES users(id)
);
-- Create order_items table
CREATE TABLE IF NOT EXISTS order_items (
id INTEGER PRIMARY KEY AUTOINCREMENT,
order_id INTEGER NOT NULL,
product_id INTEGER NOT NULL,
quantity INTEGER NOT NULL,
unit_price DECIMAL(10,2) NOT NULL,
FOREIGN KEY (order_id) REFERENCES orders(id),
FOREIGN KEY (product_id) REFERENCES products(id)
);
-- Insert sample users
INSERT INTO users (name, email) VALUES
('John Doe', 'john@example.com'),
('Jane Smith', 'jane@example.com'),
('Bob Johnson', 'bob@example.com'),
('Alice Brown', 'alice@example.com'),
('Charlie Wilson', 'charlie@example.com');
-- Insert sample products
INSERT INTO products (name, description, price, category, stock_quantity) VALUES
('Laptop', 'High-performance laptop for professionals', 899.99, 'Electronics', 15),
('Smartphone', 'Latest smartphone with advanced features', 699.99, 'Electronics', 25),
('Coffee Maker', 'Automatic coffee maker for home use', 89.99, 'Home & Kitchen', 30),
('Running Shoes', 'Comfortable running shoes for athletes', 129.99, 'Sports', 20),
('Backpack', 'Durable backpack for daily use', 49.99, 'Fashion', 40),
('Bluetooth Speaker', 'Portable wireless speaker', 79.99, 'Electronics', 18),
('Yoga Mat', 'Non-slip yoga mat for fitness', 29.99, 'Sports', 35),
('Desk Lamp', 'LED desk lamp with adjustable brightness', 39.99, 'Home & Kitchen', 22);
-- Insert sample orders
INSERT INTO orders (user_id, total_amount, status) VALUES
(1, 899.99, 'completed'),
(2, 209.98, 'completed'),
(3, 159.98, 'pending'),
(4, 699.99, 'completed'),
(5, 89.99, 'shipped');
-- Insert sample order items
INSERT INTO order_items (order_id, product_id, quantity, unit_price) VALUES
(1, 1, 1, 899.99), -- John bought a laptop
(2, 3, 1, 89.99), -- Jane bought a coffee maker
(2, 7, 1, 29.99), -- Jane also bought a yoga mat
(2, 8, 1, 39.99), -- Jane also bought a desk lamp
(3, 5, 1, 49.99), -- Bob bought a backpack
(3, 6, 1, 79.99), -- Bob also bought a bluetooth speaker
(3, 8, 1, 39.99), -- Bob also bought a desk lamp
(4, 2, 1, 699.99), -- Alice bought a smartphone
(5, 3, 1, 89.99); -- Charlie bought a coffee maker
-- Update some user last_login times
UPDATE users SET last_login = datetime('now', '-1 day') WHERE id = 1;
UPDATE users SET last_login = datetime('now', '-3 days') WHERE id = 2;
UPDATE users SET last_login = datetime('now', '-7 days') WHERE id = 3;
UPDATE users SET last_login = datetime('now', '-2 days') WHERE id = 4;
UPDATE users SET last_login = datetime('now', '-5 days') WHERE id = 5;
-- Create indexes for better performance
CREATE INDEX IF NOT EXISTS idx_users_email ON users(email);
CREATE INDEX IF NOT EXISTS idx_products_category ON products(category);
CREATE INDEX IF NOT EXISTS idx_orders_user_id ON orders(user_id);
CREATE INDEX IF NOT EXISTS idx_orders_status ON orders(status);
CREATE INDEX IF NOT EXISTS idx_order_items_order_id ON order_items(order_id);
CREATE INDEX IF NOT EXISTS idx_order_items_product_id ON order_items(product_id);

166
dexto/agents/database-agent/database-agent.yml Normal file
View File

@@ -0,0 +1,166 @@
# Database Interaction Agent
# This agent demonstrates an alternative approach to building database interfaces
# Instead of traditional web UIs with forms and buttons, this agent provides
# natural language interaction with database operations through MCP tools
mcpServers:
# SQLite database server for direct database interaction
sqlite:
type: stdio
command: npx
args:
- -y
- "@executeautomation/database-server"
- "${{dexto.agent_dir}}/data/example.db"
timeout: 30000
connectionMode: strict
# Filesystem access for database file management and schema inspection
filesystem:
type: stdio
command: npx
args:
- -y
- "@modelcontextprotocol/server-filesystem"
- .
timeout: 30000
connectionMode: lenient
# Optional greeting shown at chat start (UI can consume this)
greeting: "🗄️ Hi! I'm your Database Agent. What would you like to explore?"
# System prompt that defines the agent's database interaction capabilities
systemPrompt:
contributors:
- id: primary
type: static
priority: 0
content: |
You are a Database Interaction Agent that provides natural language access to database operations
and analytics. You orchestrate database operations through intelligent conversation and tool usage.
## Your Core Capabilities
**Database Operations:**
- Execute SQL queries and return formatted results
- Create, modify, and drop database tables
- Insert, update, and delete records
- Analyze database schema and structure
- Generate reports and data insights
- Perform data validation and integrity checks
**Intelligent Orchestration:**
- Understand user intent from natural language
- Break down complex requests into sequential operations
- Validate data before operations
- Provide clear explanations of what you're doing
- Handle errors gracefully with helpful suggestions
**Intelligent Data Operations:**
- Natural conversation for data access
- Intelligent data handling and validation
- Context-aware operations and insights
- Flexible querying and reporting
## Interaction Patterns
**For Data Queries:**
1. Understand what the user wants to know
2. Formulate appropriate SQL queries
3. Execute and format results clearly
4. Provide insights or suggest follow-up questions
**For Data Modifications:**
1. Confirm the user's intent
2. Validate data integrity
3. Execute the operation safely
4. Confirm success and show results
**For Schema Operations:**
1. Analyze current structure
2. Plan the changes needed
3. Execute modifications
4. Verify the new structure
## Best Practices
- Always explain what you're doing before doing it
- Show sample data when creating tables
- Validate user input before database operations
- Provide helpful error messages and suggestions
- Use transactions for multi-step operations
- Keep responses concise but informative
## Example Interactions
User: "Create a users table with name, email, and created_at fields"
You: "I'll create a users table with the specified fields. Let me set this up for you..."
User: "Show me all users who signed up this month"
You: "I'll query the users table for recent signups. Let me get that information..."
User: "Add a new user named John Doe with email john@example.com"
You: "I'll insert a new user record for John Doe. Let me add that to the database..."
Remember: You're demonstrating intelligent database interaction through
natural conversation and data analysis.
- id: date
type: dynamic
priority: 10
source: date
enabled: true
# Storage configuration
storage:
cache:
type: in-memory
database:
type: sqlite
blob:
type: local # CLI provides storePath automatically
maxBlobSize: 52428800 # 50MB per blob
maxTotalSize: 1073741824 # 1GB total storage
cleanupAfterDays: 30
# LLM configuration for intelligent database interactions
llm:
provider: openai
model: gpt-5-mini
apiKey: $OPENAI_API_KEY
temperature: 0.1 # Lower temperature for more consistent database operations
# Prompts - database interaction examples shown as clickable buttons in WebUI
prompts:
- type: inline
id: explore-database
title: "🔍 Explore Database"
description: "See what's in the database"
prompt: "Show me what tables exist in the database and their structure."
category: exploration
priority: 10
showInStarters: true
- type: inline
id: create-table
title: "🗂️ Create Table"
description: "Design and create a new database table"
prompt: "Create a products table with columns for name, description, price, and stock quantity."
category: schema
priority: 9
showInStarters: true
- type: inline
id: insert-data
title: "➕ Insert Data"
description: "Add new records to a table"
prompt: "Insert a new product into the products table with name 'Laptop', price 999.99, and stock 15."
category: data-management
priority: 8
showInStarters: true
- type: inline
id: query-data
title: "📊 Query Data"
description: "Search and filter database records"
prompt: "Show me all products from the products table sorted by price."
category: queries
priority: 7
showInStarters: true

64
dexto/agents/database-agent/setup-database.sh Executable file
View File

@@ -0,0 +1,64 @@
#!/bin/bash
# Exit immediately on errors, unset variables, or pipeline failures
set -euo pipefail
# Get the directory where this script is located
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Setup script for Database Interaction Agent
# This script creates the data directory and initializes the database with sample data
echo "🚀 Setting up Database Interaction Agent..."
# Create data directory if it doesn't exist
echo "📁 Creating data directory..."
mkdir -p "${SCRIPT_DIR}/data"
# Check if SQLite is available
if ! command -v sqlite3 &> /dev/null; then
echo "❌ SQLite3 is not installed. Please install SQLite3 first:"
echo " macOS: brew install sqlite3"
echo " Ubuntu/Debian: sudo apt-get install sqlite3"
echo " Windows: Download from https://www.sqlite.org/download.html"
exit 1
fi
# Initialize database with sample data
echo "🗄️ Initializing database with sample data..."
# Remove existing database if it exists to avoid constraint violations
if [ -f "${SCRIPT_DIR}/data/example.db" ]; then
echo "🗑️ Removing existing database..."
rm "${SCRIPT_DIR}/data/example.db"
fi
sqlite3 "${SCRIPT_DIR}/data/example.db" < "${SCRIPT_DIR}/database-agent-example.sql"
# Verify the database was created successfully
if [ -f "${SCRIPT_DIR}/data/example.db" ]; then
echo "✅ Database created successfully!"
# Show some basic stats
echo "📊 Database statistics:"
echo " Tables: $(sqlite3 "${SCRIPT_DIR}/data/example.db" "SELECT COUNT(*) FROM sqlite_master WHERE type='table';")"
echo " Users: $(sqlite3 "${SCRIPT_DIR}/data/example.db" "SELECT COUNT(*) FROM users;")"
echo " Products: $(sqlite3 "${SCRIPT_DIR}/data/example.db" "SELECT COUNT(*) FROM products;")"
echo " Orders: $(sqlite3 "${SCRIPT_DIR}/data/example.db" "SELECT COUNT(*) FROM orders;")"
echo ""
echo "🎉 Database setup complete!"
echo ""
echo "You can now run the Database Interaction Agent with:"
echo " dexto --agent agents/database-agent.yml"
echo ""
echo "Example interactions you can try:"
echo " - 'Show me all users'"
echo " - 'List products under \$100'"
echo " - 'Create a new user named Test User with email test@example.com'"
echo " - 'Show me total sales by category'"
echo " - 'Find users who haven't logged in for more than 5 days'"
else
echo "❌ Failed to create database. Please check the SQL file and try again."
exit 1
fi

217
dexto/agents/default-agent.yml Normal file
View File

@@ -0,0 +1,217 @@
# describes the mcp servers to use
mcpServers:
filesystem:
type: stdio
command: npx
args:
- -y
- "@modelcontextprotocol/server-filesystem"
- .
playwright:
type: stdio
command: npx
args:
- -y
- "@playwright/mcp@latest"
# System prompt configuration - defines the agent's behavior and instructions
systemPrompt:
contributors:
- id: primary
type: static
priority: 0
content: |
You are a helpful AI assistant with access to tools.
Use these tools when appropriate to answer user queries.
You can use multiple tools in sequence to solve complex problems.
After each tool result, determine if you need more information or can provide a final answer.
- id: date
type: dynamic
priority: 10
source: date
enabled: true
# Memory configuration - controls how memories are included in system prompt
memories:
enabled: true
priority: 40
includeTimestamps: false
includeTags: true
limit: 10
pinnedOnly: false
# Optional greeting shown at chat start (UI can consume this)
greeting: "Hi! I'm Dexto — how can I help today?"
# LLM configuration - describes the language model to use
llm:
provider: openai
model: gpt-5-mini
apiKey: $OPENAI_API_KEY
# Optional: Control which media types are expanded for LLM consumption
# If omitted, uses model capabilities from registry (recommended default)
# Supports MIME patterns with wildcards (e.g., "image/*", "video/mp4")
# allowedMediaTypes:
# - "image/*" # All images (png, jpg, gif, etc.)
# - "application/pdf" # PDF documents
# - "audio/*" # All audio formats
# Note: Unsupported types become descriptive placeholders like: [Video: demo.mp4 (5.2 MB)]
# Logger configuration - multi-transport logging system
# The CLI automatically adds a file transport for agent-specific logs
# logger:
# level: info # error | warn | info | debug | silly
# transports:
# - type: console
# colorize: true
# - type: file
# path: ./logs/agent.log
# maxSize: 10485760 # 10MB
# maxFiles: 5
storage:
cache:
type: in-memory
database:
type: sqlite
# path: ./data/dexto.db # Optional: customize database location
blob:
type: local # CLI provides storePath automatically
# storePath: ./data/blobs # Optional: customize blob storage location (defaults to agent-specific path)
maxBlobSize: 52428800 # 50MB per blob
maxTotalSize: 1073741824 # 1GB total storage
cleanupAfterDays: 30
toolConfirmation:
mode: manual
# timeout: <optional> # Time to wait for approval (ms). Omit for no timeout (wait indefinitely)
allowedToolsStorage: memory # 'memory' or 'storage' for persisting allowed tools
# Optional: Static tool policies for fine-grained allow/deny control
toolPolicies:
# Tools that never require approval (low-risk, common operations)
alwaysAllow:
- internal--ask_user
- mcp--read_file
- mcp--list_directory
- mcp--list_allowed_directories
# Tools that are always denied (high-risk, destructive operations)
# Deny list takes precedence over allow list
# alwaysDeny:
# - mcp--filesystem--delete_file
# - mcp--playwright--execute_script
# Elicitation configuration - separate from tool confirmation
# Allows auto-approve for tools while still supporting user input requests
elicitation:
enabled: true # Enable ask_user tool and MCP server elicitations
# timeout: <optional> # Time to wait for user input (ms). Omit for no timeout (wait indefinitely)
# Internal tools - built-in Dexto capabilities
internalTools:
- ask_user # Allows the agent to ask you questions and collect structured input
- delegate_to_url
- list_resources
- get_resource
# Internal resources configuration - manages file system access and blob storage
# NOTE: Blob storage capacity and backend settings are in the 'storage.blob' section above
internalResources:
enabled: true
resources:
# Filesystem resource - provides read access to local files for the agent
- type: filesystem
paths: ["."] # Directories to expose
maxFiles: 50 # Maximum number of files to index
maxDepth: 3 # Maximum directory depth to traverse
includeHidden: false # Include hidden files/directories
includeExtensions: [".txt", ".md", ".json", ".yaml", ".yml", ".js", ".ts", ".py", ".html", ".css"]
# Blob resource - enables large file upload/storage (settings in storage.blob section above)
- type: blob
# Plugin system - built-in plugins for content policy and response sanitization
# plugins:
# # ContentPolicy - validates and sanitizes input before sending to LLM
# contentPolicy:
# priority: 10 # Lower priority = runs first
# blocking: true # Blocks execution if validation fails
# maxInputChars: 50000 # Maximum input length (characters)
# redactEmails: true # Redact email addresses from input
# redactApiKeys: true # Redact potential API keys from input
# enabled: true # Enable this plugin
# # ResponseSanitizer - sanitizes LLM responses before returning to user
# responseSanitizer:
# priority: 900 # Higher priority = runs near the end
# blocking: false # Non-blocking (logs warnings but doesn't stop)
# redactEmails: true # Redact email addresses from responses
# redactApiKeys: true # Redact potential API keys from responses
# maxResponseLength: 100000 # Maximum response length (characters)
# enabled: true # Enable this plugin
# # Custom plugins can be added here (see documentation)
# # custom:
# # - name: tenant-auth
# # module: "${{dexto.agent_dir}}/plugins/tenant-auth.ts"
# # enabled: true
# # blocking: true
# # priority: 100
# # config:
# # enforceQuota: true
# Prompts - inline prompts shown as clickable buttons in WebUI (showInStarters: true)
prompts:
- type: inline
id: quick-start
title: "📚 Quick Start Guide"
description: "Learn the basics and see what you can do"
prompt: "I'd like to get started quickly. Can you show me a few examples of what you can do and help me understand how to work with you?"
category: learning
priority: 9
showInStarters: true
- type: inline
id: tool-demo
title: "⚡ Tool Demonstration"
description: "See the tools in action with practical examples"
prompt: "I'd like to see your tools in action. Can you pick one of your most interesting tools and demonstrate it with a practical example? Show me what it can do and how it works."
category: tools
priority: 5
showInStarters: true
- type: inline
id: snake-game
title: "🐍 Create Snake Game"
description: "Build a fun interactive game with HTML, CSS, and JavaScript"
prompt: "Create a snake game in a new directory with HTML, CSS, and JavaScript, then open it in the browser for me to play."
category: coding
priority: 4
showInStarters: true
- type: inline
id: connect-tools
title: "🔧 Connect New Tools"
description: "Browse and add MCP servers to extend capabilities"
prompt: "I want to connect new tools to expand my capabilities. Can you help me understand what MCP servers are available and how to add them?"
category: tools
priority: 3
showInStarters: true
# Telemetry configuration (optional) - OpenTelemetry for distributed tracing
# telemetry:
# serviceName: dexto-default-agent
# enabled: true
# tracerName: dexto-tracer
# export:
# type: otlp # 'otlp' for production, 'console' for development
# protocol: http # 'http' or 'grpc'
# endpoint: http://127.0.0.1:4318/v1/traces # OTLP collector endpoint
# headers: # Optional headers for authentication
# Authorization: Bearer <token>
## To use Google Gemini, replace the LLM section with Google Gemini configuration below
## Similar for anthropic/groq/etc.
# llm:
# provider: google
# model: gemini-2.5-pro
# apiKey: $GOOGLE_GENERATIVE_AI_API_KEY

22
dexto/agents/examples/README.md Normal file
View File

@@ -0,0 +1,22 @@
# Configuration Examples
This folder contains examples for agents with different configurations. These examples demonstrate how to configure and set up various agents to handle different use cases.
You can directly plug in these configuration files and try them out on your local system to see the power of different AI Agents!
## Available Examples
### `linear-task-manager.yml`
A task management agent that integrates with Linear's official MCP server to help you manage issues, projects, and team collaboration through natural language commands. Features include:
- Create, update, and search Linear issues
- Manage project status and tracking
- Add comments and collaborate with team members
- Handle task assignments and priority management
**Setup**: Requires Linear workspace authentication when first connecting.
### Other Examples
- `email_slack.yml` - Email and Slack integration
- `notion.yml` - Notion workspace management
- `ollama.yml` - Local LLM integration
- `website_designer.yml` - Web design assistance

26
dexto/agents/examples/email_slack.yml Normal file
View File

@@ -0,0 +1,26 @@
# Email to Slack Automation Configuration
# This agent monitors emails and posts summaries to Slack
mcpServers:
gmail:
type: sse
url: "composio-url"
slack:
type: stdio
command: "npx"
args:
- -y
- "@modelcontextprotocol/server-slack"
env:
SLACK_BOT_TOKEN: "slack-bot-token"
SLACK_TEAM_ID: "slack-team-id"
# System prompt - defines the agent's behavior for email processing
systemPrompt: |
Prompt the user to provide the information needed to answer their question or identify them on Slack.
Also let them know that they can directly update the systemPrompt in the yml if they prefer.
# LLM Configuration
llm:
provider: openai
model: gpt-5-mini
apiKey: $OPENAI_API_KEY

58
dexto/agents/examples/linear-task-manager.yml Normal file
View File

@@ -0,0 +1,58 @@
# Linear Task Management Agent
# This agent integrates with Linear's MCP server to manage tasks, issues, and projects
# through natural language commands.
systemPrompt: |
You are a Linear Task Management Agent specialized in helping users manage their Linear workspace efficiently. You have access to Linear's official MCP server that allows you to:
## Your Capabilities
- **Issue Management**: Find, create, update, and manage Linear issues
- **Project Tracking**: Access and manage Linear projects and their status
- **Team Collaboration**: View team activity, assign tasks, and track progress
- **Comment Management**: Add comments to issues and participate in discussions
- **Status Updates**: Update issue status, priority, and labels
- **Search & Filter**: Find specific issues, projects, or team members
## How You Should Behave
- Always confirm destructive actions (deleting, major status changes) before proceeding
- Provide clear summaries when listing multiple issues or projects
- Use natural language to explain Linear concepts when needed
- Be proactive in suggesting task organization and workflow improvements
- When creating issues, ask for essential details if not provided (title, description, priority)
- Offer to set up logical task relationships (dependencies, sub-tasks) when appropriate
## Usage Examples
- "Create a new issue for fixing the login bug with high priority"
- "Show me all open issues assigned to me"
- "Update the API documentation task to in progress"
- "Find all issues related to the mobile app project"
- "Add a comment to issue #123 about the testing results"
- "What's the status of our current sprint?"
mcpServers:
linear:
type: stdio
command: npx
args:
- -y
- mcp-remote
- https://mcp.linear.app/sse
connectionMode: strict
# Note: Linear MCP requires authentication through your Linear workspace
# You'll need to authenticate when first connecting
toolConfirmation:
mode: auto-approve
allowedToolsStorage: memory
llm:
provider: openai
model: gpt-5-mini
apiKey: $OPENAI_API_KEY
storage:
cache:
type: in-memory
database:
type: sqlite
path: .dexto/database/linear-task-manager.db

31
dexto/agents/examples/notion.yml Normal file
View File

@@ -0,0 +1,31 @@
# Refer https://github.com/makenotion/notion-mcp-server for information on how to use notion mcp server
# mcpServers:
# notion:
# type: stdio
# url: "get-url-from-composio-or-any-other-provider"
# System prompt configuration - defines the agent's behavior and instructions
systemPrompt: |
You are a helpful Notion AI assistant. Your primary goals are to:
1. Help users organize and manage their Notion workspace effectively
2. Assist with creating, editing, and organizing pages and databases
3. Provide guidance on Notion features and best practices
4. Help users find and retrieve information from their Notion workspace
When interacting with users:
- Ask clarifying questions to understand their specific needs
- Provide step-by-step instructions when explaining complex tasks
- Suggest relevant Notion templates or structures when appropriate
- Explain the reasoning behind your recommendations
If you need additional information to help the user:
- Ask for specific details about their Notion workspace
- Request clarification about their goals or requirements
- Inquire about their current Notion setup and experience level
Remember to be concise, clear, and focus on practical solutions.
llm:
provider: openai
model: gpt-5-mini
apiKey: $OPENAI_API_KEY

67
dexto/agents/examples/ollama.yml Normal file
View File

@@ -0,0 +1,67 @@
# describes the mcp servers to use
mcpServers:
filesystem:
type: stdio
command: npx
args:
- -y
- "@modelcontextprotocol/server-filesystem"
- .
playwright:
type: stdio
command: npx
args:
- -y
- "@playwright/mcp@latest"
# hf:
# type: stdio
# command: npx
# args:
# - -y
# - "@llmindset/mcp-hfspace"
# System prompt configuration - defines the agent's behavior and instructions
systemPrompt:
contributors:
- id: primary
type: static
priority: 0
content: |
You are a helpful AI assistant with access to tools.
Use these tools when appropriate to answer user queries.
You can use multiple tools in sequence to solve complex problems.
After each tool result, determine if you need more information or can provide a final answer.
- id: date
type: dynamic
priority: 10
source: date
enabled: true
# first start the ollama server
# ollama run gemma3n:e2b
# then run the following command to start the agent:
# dexto --agent <path_to_ollama.yml>
# dexto --agent <path_to_ollama.yml> for web ui
llm:
provider: openai-compatible
model: gemma3n:e2b
baseURL: http://localhost:11434/v1
apiKey: $OPENAI_API_KEY
maxInputTokens: 32768
# Storage configuration - uses a two-tier architecture: cache (fast, ephemeral) and database (persistent, reliable)
# Memory cache with file-based database (good for development with persistence)
# storage:
# cache:
# type: in-memory
# database:
# type: sqlite
# path: ./data/dexto.db
## To use Google Gemini, replace the LLM section with Google Gemini configuration below
## Similar for anthropic/groq/etc.
# llm:
# provider: google
# model: gemini-2.0-flash
# apiKey: $GOOGLE_GENERATIVE_AI_API_KEY

34
dexto/agents/examples/website_designer.yml Normal file
View File

@@ -0,0 +1,34 @@
# describes the mcp servers to use
mcpServers:
filesystem:
type: stdio
command: npx
args:
- -y
- "@modelcontextprotocol/server-filesystem"
- .
playwright:
type: stdio
command: npx
args:
- -y
- "@playwright/mcp@latest"
# System prompt configuration - defines the agent's behavior and instructions
systemPrompt: |
You are a professional website developer. You design beautiful, aesthetic websites.
Use these tools when appropriate to answer user queries.
You can use multiple tools in sequence to solve complex problems.
After each tool result, determine if you need more information or can provide a final answer.
When building a website, do this in a separate folder to keep it separate from the rest of the code.
The website should look clean, professional, modern and elegant.
It should be visually appealing. Carefully consider the color scheme, font choices, and layout. I like non-white backgrounds.
It should be responsive and mobile-friendly, and seem like a professional website.
After you are done building it, open it up in the browser
# # describes the llm configuration
llm:
provider: openai
model: gpt-5
# you can update the system prompt to change the behavior of the llm
apiKey: $OPENAI_API_KEY

126
dexto/agents/explore-agent/explore-agent.yml Normal file
View File

@@ -0,0 +1,126 @@
# Explore Agent Configuration
# Lightweight, read-only agent optimized for codebase exploration
# Designed to be spawned by other agents for research tasks
# No image bundle - uses only explicitly defined tools below
# System prompt optimized for exploration tasks
systemPrompt:
contributors:
- id: primary
type: static
priority: 0
content: |
You are a fast, focused exploration agent specialized in understanding codebases and finding information.
## Your Mission
Quickly and thoroughly explore codebases to answer questions, find patterns, locate files, and understand architecture. You are optimized for speed and accuracy.
## Available Tools
You have access to read-only tools:
- `glob_files` - Find files matching patterns (e.g., "src/**/*.ts", "*.config.js")
- `grep_content` - Search for text/patterns within files
- `read_file` - Read file contents
## Exploration Strategy
### For "quick" searches:
- Single glob or grep to find the target
- Read 1-2 most relevant files
- Return focused answer
### For "medium" exploration:
- Multiple search patterns to find related files
- Read key files to understand connections
- Summarize findings with file references
### For "very thorough" analysis:
- Comprehensive search across multiple naming conventions
- Trace imports, exports, and dependencies
- Map relationships between components
- Provide detailed analysis with evidence
## Guidelines
- Start with broad searches, then narrow down
- Use glob for file discovery, grep for content search
- Try multiple naming conventions (camelCase, snake_case, kebab-case, PascalCase)
- Check common locations: src/, lib/, packages/, tests/, config/
- Report what you found AND what you didn't find
- Include file paths and line numbers in your response
- Be concise but complete
## Response Format
Structure your response as:
1. **Summary** - Brief answer to the question
2. **Key Files** - List of relevant files found
3. **Details** - Specific findings with code references
4. **Notes** - Any caveats or areas that need further exploration
# LLM configuration - Haiku for speed and cost efficiency
# When spawned as a sub-agent, this config may be overridden by parent's LLM
# if the API key is not available (with a warning to use 'dexto login')
llm:
provider: anthropic
model: claude-haiku-4-5-20251001
apiKey: $ANTHROPIC_API_KEY
# Minimal storage - in-memory only for ephemeral use
storage:
cache:
type: in-memory
database:
type: in-memory
blob:
type: in-memory
# Auto-approve all tools since they're read-only
toolConfirmation:
mode: auto-approve
allowedToolsStorage: memory
# No internal tools needed for exploration
internalTools: []
# Read-only filesystem tools only - explicitly enable only read operations
customTools:
- type: filesystem-tools
enabledTools: ["read_file", "glob_files", "grep_content"] # Read-only tools only
allowedPaths: ["."]
blockedPaths:
# Version control
- ".git"
# Binaries
- "node_modules/.bin"
# Environment files with secrets
- ".env"
- ".env.local"
- ".env.production"
- ".env.development"
- ".env.test"
- ".env.staging"
# Package manager credentials
- ".npmrc"
- ".yarnrc"
- ".pypirc"
# Git credentials
- ".git-credentials"
- ".gitconfig"
# SSH keys
- ".ssh"
# Cloud provider credentials
- ".aws"
- ".gcp"
- ".azure"
# Kubernetes config
- ".kube"
# Docker credentials
- ".docker"
blockedExtensions: [".exe", ".dll", ".so", ".dylib"]
maxFileSize: 10485760 # 10MB
enableBackups: false
# Note: This agent intentionally excludes:
# - write_file, edit_file (write operations) - not in enabledTools
# - process-tools (bash execution) - provider not included
# - agent-spawner (no sub-agent spawning) - provider not included
# This ensures it remains a safe, read-only exploration tool

109
dexto/agents/gaming-agent/gaming-agent.yml Normal file
View File

@@ -0,0 +1,109 @@
# Gaming Agent - Plays GameBoy games with save state support
mcpServers:
gameboy:
type: stdio
command: npx
args:
- -y
- "@truffle-ai/gameboy-server@0.1.0"
timeout: 60000
connectionMode: strict
greeting: "Hey! I'm your Gaming Agent. Want to continue a saved game or start something new?"
systemPrompt:
contributors:
- id: primary
type: static
priority: 0
content: |
You are a Gaming Agent that plays GameBoy games. You see the screen and press buttons.
## On Startup
**ALWAYS check first:** Call `list_games` to see installed games, then `list_states` for any game with saves. Ask user if they want to continue from a save or start fresh.
## Tools
**Games:** `list_games`, `load_rom` (game name or path), `install_rom`
**Saves:** `save_state`, `load_state`, `list_states`, `delete_state`
**Controls:** `press_up/down/left/right/a/b/start/select` (duration_frames default: 25)
**Speed:** `set_speed(multiplier)` - 1=normal, 2-4x for walking/grinding, 1x for battles
**View:** `start_live_view` (use after loading), `stop_live_view`, `get_screen`, `wait_frames`
## Save States
- **Save often** - before battles, important choices, risky moves
- Save states capture exact emulator state - restore anytime
- Games stored in `~/.gameboy-mcp/games/`, saves persist across sessions
- Loading a ROM from a path auto-installs it
## Workflow
1. Check for existing games/saves → offer to continue
2. `load_rom` (by name or path) → `start_live_view`
3. Play with button presses, save frequently
4. Before anything risky: `save_state`
## Pokemon Tips
- Title: START → Menus: D-pad + A/B → Text: spam A
- Use 3-4x speed for walking/exploring, 1x for battles and menus
- Save before gym battles, catching legendaries, tough trainers
- id: date
type: dynamic
priority: 10
source: date
enabled: true
storage:
cache:
type: in-memory
database:
type: sqlite
blob:
type: local
maxBlobSize: 52428800
maxTotalSize: 1073741824
cleanupAfterDays: 30
llm:
provider: anthropic
model: claude-haiku-4-5-20251001
apiKey: $ANTHROPIC_API_KEY
toolConfirmation:
mode: auto-approve
allowedToolsStorage: memory
prompts:
- type: inline
id: continue-save
title: "Continue from Save"
description: "Resume from a previous save state"
prompt: "Check my installed games and save states. Show me what I can continue from."
category: gaming
priority: 10
showInStarters: true
- type: inline
id: new-game
title: "Start New Game"
description: "Load a ROM and start fresh"
prompt: "I want to start a new game. Show me my installed games or I'll give you a ROM path."
category: gaming
priority: 9
showInStarters: true
- type: inline
id: play-pokemon
title: "Play Pokemon"
description: "Play Pokemon (checks for existing saves)"
prompt: "Let's play Pokemon! Check if I have any Pokemon saves to continue, or start a new game."
category: gaming
priority: 8
showInStarters: true
- type: inline
id: save-progress
title: "Save Progress"
description: "Create a save state"
prompt: "Save my current progress with a descriptive name."
category: gaming
priority: 7
showInStarters: true

58
dexto/agents/github-agent/README.md Normal file
View File

@@ -0,0 +1,58 @@
# GitHub Integration Agent
Bring GitHub context into any workspace. This agent starts the `@truffle-ai/github-mcp-server` in `stdio` mode so the assistant can explore repositories, manage pull requests, and automate GitHub project workflows directly from chat.
## What You Get
- Full coverage of GitHub toolsets (repos, pull requests, issues, actions, discussions, notifications, security, projects, and more)
- Automatic OAuth device-flow login with cached tokens, no personal access token required for most users
- Safe-guarded write operations (issues, PRs, workflow runs, comments, etc.) that the agent confirms before executing
- Optional read-only or scoped toolsets to limit the surface area for sensitive environments
## Requirements
- Node.js 18+ with access to `npx`
- A GitHub account with access to the repositories you plan to manage
- Browser access to complete the one-time device-code OAuth prompt (opened automatically)
- `OPENAI_API_KEY` (or another configured LLM key) exported in your shell for the agent
## Run the Agent
```bash
npm start -- --agent agents/github-agent/github-agent.yml
```
The CLI launches `npx -y @truffle-ai/github-mcp-server stdio`. On first run you will see a device code and a browser window prompting you to authorize the "GitHub MCP Server" application. Approving the flow stores an access token at:
```
~/.config/truffle/github-mcp/<host>-token.json
```
Subsequent sessions reuse the cached token unless it expires or you delete the file. Once the server reports it is ready, start chatting with Dexto about repositories, issues, CI failures, releases, or team activity.
## Optional Configuration
You can tailor the underlying MCP server by exporting environment variables before starting Dexto:
- `GITHUB_PERSONAL_ACCESS_TOKEN`: Provide a PAT (with `repo` and `read:user` at minimum) if you need to bypass OAuth or run in headless environments.
- `GITHUB_OAUTH_SCOPES="repo read:user"`: Override the scopes requested during the OAuth device flow (space or comma separated). Use this to request additional permissions (e.g., `gist`) or limit scopes in tightly controlled environments.
- `GITHUB_TOOLSETS="repos,issues,pull_requests,actions"`: Restrict which groups of tools the agent loads. Available groups include `repos`, `issues`, `pull_requests`, `actions`, `notifications`, `discussions`, `projects`, `code_security`, `dependabot`, `secret_protection`, `security_advisories`, `users`, `orgs`, `gists`, `context`, and `experiments`.
- `GITHUB_READ_ONLY=1`: Offer only read-only tools; write operations will be hidden.
- `GITHUB_DYNAMIC_TOOLSETS=1`: Enable on-demand toolset discovery so the model only activates tools as needed.
- `GITHUB_HOST=https://github.mycompany.com`: Point the agent at GitHub Enterprise Server or ghe.com tenants.
- `GITHUB_LOG_FILE=~/github-mcp.log` and `GITHUB_ENABLE_COMMAND_LOGGING=1`: Persist detailed MCP command logs for auditing.
- `GITHUB_CONTENT_WINDOW_SIZE=7500`: Increase the amount of content retrieved for large diffs or logs.
Refer to the upstream [`github-mcp-server`](https://github.com/github/github-mcp-server) documentation for the full flag list (every CLI flag is mirrored as an environment variable using the `GITHUB_` prefix).
## Switching to the Remote GitHub MCP Server (optional)
If you prefer to connect to the GitHub-hosted remote MCP server instead of running the bundled binary, replace the `mcpServers.github` block in `github-agent.yml` with:
```yaml
mcpServers:
github:
type: http
url: https://api.githubcopilot.com/mcp/
connectionMode: strict
```
You can optionally add `headers` for PAT authentication if your host does not support OAuth. Restart Dexto after saving the change.
## Resetting Authorization
To force a new OAuth login, delete the cached token file (`rm ~/.config/truffle/github-mcp/*-token.json`) and relaunch the agent. The next startup will trigger a fresh device flow.

107
dexto/agents/github-agent/github-agent.yml Normal file
View File

@@ -0,0 +1,107 @@
# GitHub Integration Agent configuration
# Connects Dexto to GitHub via the bundled GitHub MCP server binary
mcpServers:
github:
# type: http
# url: https://api.githubcopilot.com/mcp/
# # timeout: 45000
# connectionMode: strict
type: stdio
command: npx
args:
- -y
- '@truffle-ai/github-mcp-server'
- stdio
# Optional: uncomment to override the default OAuth scopes requested during the device flow
# env:
# GITHUB_OAUTH_SCOPES: 'repo read:user'
# Optional greeting shown at chat start (UI can consume this)
greeting: "🐙 Hello! I'm your GitHub Agent. How can I help with your repositories?"
systemPrompt:
contributors:
- id: primary
type: static
priority: 0
content: |
You are the GitHub Integration Agent for Dexto. Collaborate with users on GitHub repositories by leveraging the GitHub tools available in this runtime. Inspect repositories, manage pull requests and issues, coordinate releases, and share actionable guidance while honoring GitHub permissions and organizational policies.
## Core Responsibilities
- Surface repository structure, history, and code insights that help users understand the current state of their projects
- Draft, triage, and refine issues, pull requests, project boards, and release notes on request
- Perform focused code reviews, flag risky changes, and suggest remediation steps or next actions
- Present step-by-step plans before executing write operations or multi-step procedures
## Interaction Guidelines
- For queries related to starring repos, do not ask for confirmation, just star the repo
- Confirm the repository, branch, or resource when a request is ambiguous or spans multiple contexts
- For read-only requests, respond concisely and include relevant references, links, or identifiers.
- Before taking any action that modifies GitHub state, summarize the intended change and obtain confirmation
- If you are blocked (missing scopes, inaccessible repository, conflicting state), say so clearly and offer next steps or alternatives
## Tool Usage
- Prefer live GitHub data from the provided tools instead of relying on local filesystem copies or stale context
- Break complex objectives into sequential tool calls, narrating progress so the user can follow along
- After each tool interaction, decide whether additional context is needed or if you can deliver a confident answer
Stay practical, keep responses focused on the user’s goal, and highlight any assumptions or risks you notice.
- id: date
type: dynamic
priority: 10
source: date
enabled: true
# Storage configuration
storage:
cache:
type: in-memory
database:
type: sqlite
blob:
type: local # CLI provides storePath automatically
maxBlobSize: 52428800 # 50MB per blob
maxTotalSize: 1073741824 # 1GB total storage
cleanupAfterDays: 30
llm:
provider: openai
model: gpt-5-mini
apiKey: $OPENAI_API_KEY
# Prompts - GitHub operations examples shown as clickable buttons in WebUI
prompts:
- type: inline
id: repo-info
title: "📊 Repository Info"
description: "Get details about the Dexto repository"
prompt: "Show me information about the truffle-ai/dexto repository including stars, forks, and recent activity."
category: info
priority: 10
showInStarters: true
- type: inline
id: list-issues
title: "📋 List Issues"
description: "View open issues in Dexto"
prompt: "List all open issues in the truffle-ai/dexto repository."
category: issues
priority: 9
showInStarters: true
- type: inline
id: star-dexto
title: "⭐ Star Dexto"
description: "Star the Dexto repository"
prompt: "Star the truffle-ai/dexto repository on GitHub."
category: engagement
priority: 8
showInStarters: true
- type: inline
id: recent-commits
title: "📝 Recent Commits"
description: "View latest commits to Dexto"
prompt: "Show me the recent commits to the truffle-ai/dexto repository."
category: activity
priority: 7
showInStarters: true

BIN
dexto/agents/image-editor-agent/Lenna.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 34 KiB

435
dexto/agents/image-editor-agent/README.md Normal file
View File

@@ -0,0 +1,435 @@
# Image Editor Agent
A comprehensive AI agent for image editing and processing using the [Image Editor MCP Server](https://github.com/truffle-ai/mcp-servers/tree/main/src/image-editor).
This agent provides a complete suite of image manipulation tools through a Python-based MCP server built with OpenCV and Pillow.
## Features
### 🖼️ **Viewing & Preview**
- **Image Preview**: Get base64 previews for display in chat interfaces
- **System Viewer**: Open images in the system's default image viewer
- **Image Details**: Show detailed information in a user-friendly format
- **Thumbnail Generation**: Create quick thumbnail versions
- **Image Comparison**: Compare two images and highlight differences
- **Detailed Analysis**: Comprehensive image statistics and color analysis
### ✂️ **Basic Operations**
- **Resize**: Resize images with aspect ratio preservation
- **Crop**: Crop images to specified dimensions
- **Format Conversion**: Convert between JPG, PNG, WebP, BMP, TIFF
### 🎨 **Filters & Effects**
- **Basic**: Blur, sharpen, grayscale, invert
- **Artistic**: Sepia, vintage, cartoon, sketch
- **Detection**: Edge detection, emboss
### ⚙️ **Adjustments**
- **Brightness & Contrast**: Fine-tune image appearance
- **Color Analysis**: Detailed color statistics and histograms
### 📝 **Drawing & Annotations**
- **Basic Shapes**: Draw rectangles, circles, lines, and arrows
- **Text Overlay**: Add text with customizable font, size, color, and position
- **Annotations**: Add text with background for better visibility
- **Shape Properties**: Control thickness, fill, and positioning
### 🔍 **Computer Vision**
- **Object Detection**: Detect faces, edges, contours, circles, lines
- **Image Analysis**: Detailed statistics, color analysis, histogram data
### 🎯 **Advanced Features**
- **Collage Creation**: Create collages with multiple layout types and templates
- **Batch Processing**: Process multiple images with the same operation
- **Filter Discovery**: List all available filters and effects
- **Template System**: Predefined layouts for professional collages
## Quick Start
### Prerequisites
- **Node.js 20+**: For the Dexto framework
- **Python 3.10+**: Automatically managed by the MCP server
### Installation
1. **Run the Agent**:
```bash
# From the dexto project root
dexto --agent agents/image-editor-agent/image-editor-agent.yml
```
That's it! The MCP server will be automatically downloaded and installed via `uvx` on first run.
## Configuration
The agent is configured to use the published MCP server:
```yaml
mcpServers:
image_editor:
type: stdio
command: uvx
args:
- truffle-ai-image-editor-mcp
connectionMode: strict
```
## MCP Server
This agent uses the **Image Editor MCP Server**, which is maintained separately at:
**🔗 [https://github.com/truffle-ai/mcp-servers/tree/main/src/image-editor](https://github.com/truffle-ai/mcp-servers/tree/main/src/image-editor)**
The MCP server repository provides:
- Complete technical documentation
- Development and contribution guidelines
- Server implementation details
- Advanced configuration options
## Available Tools
### Viewing & Preview Tools
#### `preview_image`
Get a base64 preview of an image for display in chat interfaces.
**Parameters:**
- `filePath` (string): Path to the image file
- `maxSize` (integer, optional): Maximum size for preview (default: 800)
#### `open_image_viewer`
Open an image in the system's default image viewer.
**Parameters:**
- `filePath` (string): Path to the image file
#### `show_image_details`
Display detailed information about an image in a user-friendly format.
**Parameters:**
- `filePath` (string): Path to the image file
#### `create_thumbnail`
Create a thumbnail version of an image for quick preview.
**Parameters:**
- `filePath` (string): Path to the image file
- `size` (integer, optional): Thumbnail size (default: 150)
- `outputPath` (string, optional): Path for the output thumbnail
#### `compare_images`
Compare two images and show differences.
**Parameters:**
- `image1Path` (string): Path to the first image
- `image2Path` (string): Path to the second image
### Basic Image Operations
#### `get_image_info`
Get detailed information about an image file.
**Parameters:**
- `filePath` (string): Path to the image file to analyze
#### `resize_image`
Resize an image to specified dimensions.
**Parameters:**
- `inputPath` (string): Path to the input image file
- `outputPath` (string, optional): Path for the output image
- `width` (integer, optional): Target width in pixels
- `height` (integer, optional): Target height in pixels
- `maintainAspectRatio` (boolean, optional): Whether to maintain aspect ratio (default: true)
- `quality` (integer, optional): Output quality 1-100 (default: 90)
#### `crop_image`
Crop an image to specified dimensions.
**Parameters:**
- `inputPath` (string): Path to the input image file
- `outputPath` (string, optional): Path for the output image
- `x` (integer): Starting X coordinate for cropping
- `y` (integer): Starting Y coordinate for cropping
- `width` (integer): Width of the crop area
- `height` (integer): Height of the crop area
#### `convert_format`
Convert an image to a different format.
**Parameters:**
- `inputPath` (string): Path to the input image file
- `outputPath` (string, optional): Path for the output image
- `format` (string): Target format (jpg, jpeg, png, webp, bmp, tiff)
- `quality` (integer, optional): Output quality 1-100 for lossy formats (default: 90)
### Filters & Effects
#### `apply_filter`
Apply various filters and effects to an image.
**Parameters:**
- `inputPath` (string): Path to the input image file
- `outputPath` (string, optional): Path for the output image
- `filter` (string): Type of filter (blur, sharpen, grayscale, sepia, invert, edge_detection, emboss, vintage, cartoon, sketch)
- `intensity` (number, optional): Filter intensity 0.1-5.0 (default: 1.0)
#### `list_available_filters`
List all available image filters and effects.
**Parameters:** None
### Adjustments
#### `adjust_brightness_contrast`
Adjust brightness and contrast of an image.
**Parameters:**
- `inputPath` (string): Path to the input image file
- `outputPath` (string, optional): Path for the output image
- `brightness` (number, optional): Brightness adjustment -100 to 100 (default: 0)
- `contrast` (number, optional): Contrast multiplier 0.1 to 3.0 (default: 1.0)
### Drawing & Annotations
#### `draw_rectangle`
Draw a rectangle on an image.
**Parameters:**
- `inputPath` (string): Path to the input image file
- `outputPath` (string, optional): Path for the output image
- `x` (integer): X coordinate of top-left corner
- `y` (integer): Y coordinate of top-left corner
- `width` (integer): Width of the rectangle
- `height` (integer): Height of the rectangle
- `color` (string, optional): Color in hex format (default: "#FF0000")
- `thickness` (integer, optional): Line thickness (default: 3)
- `filled` (boolean, optional): Whether to fill the rectangle (default: false)
#### `draw_circle`
Draw a circle on an image.
**Parameters:**
- `inputPath` (string): Path to the input image file
- `outputPath` (string, optional): Path for the output image
- `centerX` (integer): X coordinate of circle center
- `centerY` (integer): Y coordinate of circle center
- `radius` (integer): Radius of the circle
- `color` (string, optional): Color in hex format (default: "#00FF00")
- `thickness` (integer, optional): Line thickness (default: 3)
- `filled` (boolean, optional): Whether to fill the circle (default: false)
#### `draw_line`
Draw a line on an image.
**Parameters:**
- `inputPath` (string): Path to the input image file
- `outputPath` (string, optional): Path for the output image
- `startX` (integer): X coordinate of line start
- `startY` (integer): Y coordinate of line start
- `endX` (integer): X coordinate of line end
- `endY` (integer): Y coordinate of line end
- `color` (string, optional): Color in hex format (default: "#0000FF")
- `thickness` (integer, optional): Line thickness (default: 2)
#### `draw_arrow`
Draw an arrow on an image.
**Parameters:**
- `inputPath` (string): Path to the input image file
- `outputPath` (string, optional): Path for the output image
- `startX` (integer): X coordinate of arrow start
- `startY` (integer): Y coordinate of arrow start
- `endX` (integer): X coordinate of arrow end
- `endY` (integer): Y coordinate of arrow end
- `color` (string, optional): Color in hex format (default: "#FF00FF")
- `thickness` (integer, optional): Line thickness (default: 2)
- `tipLength` (number, optional): Arrow tip length as fraction of line (default: 0.3)
#### `add_text_to_image`
Add text overlay to an image.
**Parameters:**
- `inputPath` (string): Path to the input image file
- `outputPath` (string, optional): Path for the output image
- `text` (string): Text to add to the image
- `x` (integer): X coordinate for text placement
- `y` (integer): Y coordinate for text placement
- `fontSize` (integer, optional): Font size in pixels (default: 30)
- `color` (string, optional): Text color in hex format (default: "#FFFFFF")
#### `add_annotation`
Add an annotation with background to an image.
**Parameters:**
- `inputPath` (string): Path to the input image file
- `outputPath` (string, optional): Path for the output image
- `text` (string): Text to add to the image
- `x` (integer): X coordinate for text placement
- `y` (integer): Y coordinate for text placement
- `fontSize` (integer, optional): Font size in pixels (default: 20)
- `textColor` (string, optional): Text color in hex format (default: "#FFFFFF")
- `backgroundColor` (string, optional): Background color in hex format (default: "#000000")
- `padding` (integer, optional): Padding around text (default: 5)
### Computer Vision
#### `detect_objects`
Detect objects in an image using OpenCV.
**Parameters:**
- `inputPath` (string): Path to the input image file
- `detectionType` (string): Type of detection (faces, edges, contours, circles, lines)
#### `analyze_image`
Analyze image statistics and properties.
**Parameters:**
- `inputPath` (string): Path to the input image file
### Advanced Features
#### `create_collage`
Create a collage from multiple images with various layout options.
**Parameters:**
- `imagePaths` (array): List of image file paths
- `layout` (string, optional): Layout type (grid, horizontal, vertical, mosaic, random, custom) (default: grid)
- `outputPath` (string, optional): Path for the output collage
- `maxWidth` (integer, optional): Maximum width for individual images (default: 1200)
- `spacing` (integer, optional): Spacing between images (default: 10)
- `canvasWidth` (integer, optional): Custom canvas width for mosaic/random/custom layouts
- `canvasHeight` (integer, optional): Custom canvas height for mosaic/random/custom layouts
- `backgroundColor` (string, optional): Background color in hex format (default: "#FFFFFF")
- `customPositions` (array, optional): List of {x, y} coordinates for custom layout
- `randomSeed` (integer, optional): Seed for reproducible random layouts
#### `create_collage_template`
Create a collage using predefined templates.
**Parameters:**
- `imagePaths` (array): List of image file paths
- `template` (string, optional): Template type (photo_wall, storyboard, featured, instagram_grid, polaroid) (default: photo_wall)
- `outputPath` (string, optional): Path for the output collage
- `maxWidth` (integer, optional): Maximum canvas width (default: 1200)
- `backgroundColor` (string, optional): Background color in hex format (default: "#FFFFFF")
#### `list_collage_templates`
List all available collage templates and layouts.
**Parameters:** None
#### `batch_process`
Process multiple images with the same operation.
**Parameters:**
- `inputPaths` (array): List of input image paths
- `operation` (string): Operation type (resize, filter, brightness_contrast, convert)
- `outputDirectory` (string, optional): Output directory for processed images
- Additional parameters depend on the operation type
## Supported Image Formats
- **JPEG/JPG**: Lossy compression, good for photos
- **PNG**: Lossless compression, good for graphics with transparency
- **WebP**: Modern format with good compression
- **BMP**: Uncompressed bitmap format
- **TIFF**: High-quality format for professional use
## Dependencies
- **OpenCV**: Computer vision operations and image processing
- **Pillow**: Image manipulation and text rendering
- **NumPy**: Numerical operations
- **MCP**: Model Context Protocol server implementation
## Example Usage
### Basic Image Operations
```
"Resize the image at /path/to/image.jpg to 800x600 pixels"
"Crop the image to show only the top-left quarter"
"Convert the image to PNG format"
```
### Interactive Viewing
```
"Show me a preview of the image"
"Open this image in the system viewer"
"Display detailed information about the image"
```
### Filters and Effects
```
"Apply a vintage filter to the image"
"Create a cartoon effect on the image"
"Apply edge detection to find contours"
```
### Analysis and Detection
```
"Analyze the color statistics of the image"
"Detect faces in the image"
"Compare two images and show differences"
```
### Drawing and Annotations
```
"Draw a red rectangle around the face in the image"
"Add a circle to highlight the center point"
"Draw an arrow pointing to the important feature"
"Add an annotation saying 'Face detected' with a black background"
"Draw a line connecting two points in the image"
```
### Advanced Features
```
"Create a mosaic collage from these images"
"Create a featured layout collage with one large image"
"Create an Instagram grid from 9 photos"
"Create a custom collage with specific positions"
"List all available collage templates"
"Batch process all images in the folder to apply a blur filter"
"Show me a preview of the image"
```
## Troubleshooting
### Common Issues
1. **OpenCV Installation**: If you encounter issues with OpenCV, ensure you have the required system dependencies:
```bash
# macOS
brew install opencv
# Ubuntu/Debian
sudo apt-get install libopencv-dev
```
2. **Font Issues**: If text rendering fails, the server will fall back to the default font.
3. **Memory Issues**: For large images, consider resizing before processing to avoid memory constraints.
4. **Path Issues**: Ensure all file paths are absolute or correctly relative to the working directory.
## Troubleshooting
### Common Issues
1. **Server Installation**: The MCP server will be automatically installed via `uvx` on first run. No manual setup required.
2. **OpenCV Installation**: The server includes OpenCV installation - this may take a moment on first run due to the large download (35MB+).
3. **Memory Issues**: For large images, consider resizing before processing to avoid memory constraints.
4. **Path Issues**: Ensure all file paths are absolute or correctly relative to the working directory.
## Getting Help
- **MCP Server Issues**: Report at the [mcp-servers repository](https://github.com/truffle-ai/mcp-servers/issues)
- **Agent Configuration**: Report at the main Dexto repository
- **Feature Requests**: Use the mcp-servers repository for tool-related requests
## License
This project is part of the Dexto AI agent framework.

52
dexto/agents/image-editor-agent/image-editor-agent.yml Normal file
View File

@@ -0,0 +1,52 @@
# Dexto Agent Configuration for Python Image Editor MCP Server
# Generated on 2025-07-18T19:30:00.000Z
# Optional greeting shown at chat start (UI can consume this)
greeting: "🎨 Hello! I'm your Image Editor. What image shall we create or edit today?"
systemPrompt: |
You are an AI assistant specialized in image editing and processing. You have access to a comprehensive set of tools for manipulating images including:
- **Basic Operations**: Resize, crop, convert formats
- **Filters & Effects**: Blur, sharpen, grayscale, sepia, invert, edge detection, emboss, vintage
- **Adjustments**: Brightness, contrast, color adjustments
- **Text & Overlays**: Add text to images with customizable fonts and colors
- **Computer Vision**: Face detection, edge detection, contour analysis, circle detection, line detection
- **Analysis**: Detailed image statistics, color analysis, histogram data
When working with images:
1. Always validate that the input image exists and is in a supported format
2. Provide clear feedback about what operations you're performing
3. Save processed images with descriptive names
4. Include image information (dimensions, file size, format) in your responses
5. Suggest additional enhancements when appropriate
Supported image formats: JPG, JPEG, PNG, BMP, TIFF, WebP
mcpServers:
image_editor:
type: stdio
command: uvx
args:
- truffle-ai-image-editor-mcp
connectionMode: strict
toolConfirmation:
mode: "auto-approve"
allowedToolsStorage: "memory"
llm:
provider: openai
model: gpt-5-mini
apiKey: $OPENAI_API_KEY
storage:
cache:
type: in-memory
database:
type: sqlite
blob:
type: local # CLI provides storePath automatically
maxBlobSize: 52428800 # 50MB per blob
maxTotalSize: 1073741824 # 1GB total storage
cleanupAfterDays: 30

70
dexto/agents/image-gen-agent/image-gen-agent.yml Normal file
View File

@@ -0,0 +1,70 @@
# Dexto Agent Configuration for OpenAI Image Generation MCP Server
# Uses GPT Image API (gpt-image-1) for high-quality image generation
greeting: "Hello! I'm your AI Image Generator powered by OpenAI's GPT Image API. What would you like me to create?"
systemPrompt: |
You are an expert image generation assistant powered by OpenAI's GPT Image API (gpt-image-1).
**YOUR CAPABILITIES:**
- Generate images from detailed text descriptions
- Edit existing images with masks for precise modifications
- Create transparent backgrounds for icons, sprites, and overlays
- Produce images in various formats (PNG, JPEG, WebP)
- Multiple quality levels: low (~$0.02), medium (~$0.07), high (~$0.19)
**WHEN GENERATING IMAGES:**
1. Craft detailed prompts - include style, composition, lighting, colors, and mood
2. Ask clarifying questions if the request is vague
3. Suggest appropriate settings based on use case:
- Icons/sprites: background="transparent", size="1024x1024"
- Hero images: quality="high", size="1536x1024" (landscape)
- Portrait images: size="1024x1536"
- Quick drafts: quality="low"
- Photos: output_format="jpeg"
- Graphics with transparency: output_format="png"
**WHEN EDITING IMAGES:**
1. Explain how masks work (transparent areas = regions to edit)
2. Provide clear descriptions of desired changes
3. Suggest generating multiple variations (n=2-3) for comparison
**BEST PRACTICES:**
- Default to quality="medium" for good balance of cost and quality
- Use quality="high" only for final production assets
- Confirm user's intent before generating expensive high-quality images
- Always provide the output file path after generation
- For transparent backgrounds, remind users to use PNG or WebP format
Be creative, helpful, and guide users to get the best possible results.
mcpServers:
openai_image:
type: stdio
command: npx
args:
- -y
- '@truffle-ai/openai-image-server'
env:
OPENAI_API_KEY: $OPENAI_API_KEY
connectionMode: strict
toolConfirmation:
mode: "auto-approve"
allowedToolsStorage: "memory"
llm:
provider: openai
model: gpt-5.2
apiKey: $OPENAI_API_KEY
storage:
cache:
type: in-memory
database:
type: sqlite
blob:
type: local
maxBlobSize: 52428800 # 50MB per blob
maxTotalSize: 1073741824 # 1GB total storage
cleanupAfterDays: 30

157
dexto/agents/logger-agent/logger-agent.yml Normal file
View File

@@ -0,0 +1,157 @@
# Request Logger Agent Configuration
# Demonstrates custom plugin integration with complete lifecycle testing
# Logs all user requests, tool calls, and assistant responses to ~/.dexto/logs/request-logger.log
# MCP Servers - basic filesystem and browser tools
mcpServers:
filesystem:
type: stdio
command: npx
args:
- -y
- "@modelcontextprotocol/server-filesystem"
- .
playwright:
type: stdio
command: npx
args:
- -y
- "@playwright/mcp@latest"
# System prompt configuration
systemPrompt:
contributors:
- id: primary
type: static
priority: 0
content: |
You are a helpful AI assistant with comprehensive logging enabled.
All your interactions (requests, tool calls, and responses) are being logged to help understand your behavior.
Use tools when appropriate to answer user queries. You can use multiple tools in sequence to solve complex problems.
After each tool result, determine if you need more information or can provide a final answer.
- id: date
type: dynamic
priority: 10
source: date
enabled: true
# Memory configuration - controls how memories are included in system prompt
memories:
enabled: true
priority: 40
includeTimestamps: false
includeTags: true
limit: 10
pinnedOnly: false
# Optional greeting shown at chat start
greeting: "Hi! I'm the Logger Agent — all interactions are being logged for analysis. How can I help?"
# LLM configuration
llm:
provider: openai
model: gpt-5-mini
apiKey: $OPENAI_API_KEY
# Storage configuration
storage:
cache:
type: in-memory
database:
type: sqlite
blob:
type: local # CLI provides storePath automatically
maxBlobSize: 52428800
maxTotalSize: 1073741824
cleanupAfterDays: 30
# Tool confirmation settings
toolConfirmation:
mode: manual
# timeout: omitted = infinite wait
allowedToolsStorage: memory
# Elicitation configuration - required for ask_user tool
elicitation:
enabled: true
# timeout: omitted = infinite wait
# Internal tools
internalTools:
- ask_user
# Internal resources configuration
internalResources:
enabled: true
resources:
- type: filesystem
paths: ["."]
maxFiles: 50
maxDepth: 3
includeHidden: false
includeExtensions: [".txt", ".md", ".json", ".yaml", ".yml", ".js", ".ts", ".py", ".html", ".css"]
- type: blob
# Plugin system configuration
plugins:
# Built-in plugins
contentPolicy:
priority: 10
blocking: true
maxInputChars: 50000
redactEmails: true
redactApiKeys: true
enabled: true
responseSanitizer:
priority: 900
blocking: false
redactEmails: true
redactApiKeys: true
maxResponseLength: 100000
enabled: true
# Custom Request Logger Plugin
custom:
- name: request-logger
module: "${{dexto.agent_dir}}/plugins/request-logger.ts"
enabled: true
blocking: false # Non-blocking - we just want to observe, not interfere
priority: 5 # Run early to capture original data before other plugins modify it
config: {} # Empty config uses defaults: ~/.dexto/logs/request-logger.log
# Prompts - shown as clickable buttons in WebUI
prompts:
- type: inline
id: simple-question
title: "🤔 Ask a Simple Question"
description: "Test basic request/response logging"
prompt: "What is the capital of France?"
category: learning
priority: 9
showInStarters: true
- type: inline
id: tool-usage
title: "🔧 Use a Tool"
description: "Test tool call and result logging"
prompt: "List the files in the current directory"
category: tools
priority: 8
showInStarters: true
- type: inline
id: multi-step
title: "🎯 Multi-Step Task"
description: "Test logging across multiple tool calls"
prompt: "Create a new file called test.txt with the content 'Hello from Logger Agent' and then read it back to me"
category: tools
priority: 7
showInStarters: true
- type: inline
id: check-logs
title: "📋 Check the Logs"
description: "View the request logger output"
prompt: "Can you read the file at ~/.dexto/logs/request-logger.log and show me the last 50 lines?"
category: tools
priority: 6
showInStarters: true

186
dexto/agents/logger-agent/plugins/request-logger.ts Normal file
View File

@@ -0,0 +1,186 @@
import type {
DextoPlugin,
BeforeLLMRequestPayload,
BeforeResponsePayload,
BeforeToolCallPayload,
AfterToolResultPayload,
PluginResult,
PluginExecutionContext,
} from '@core/plugins/types.js';
import { promises as fs } from 'fs';
import { homedir } from 'os';
import { join } from 'path';
/**
* Request Logger Plugin
*
* Logs all user requests and assistant responses to a file for debugging and analysis.
* Demonstrates the complete plugin lifecycle including resource management.
*
* Features:
* - Logs user input (text, images, files)
* - Logs tool calls and results
* - Logs assistant responses with token usage
* - Proper resource cleanup on shutdown
*/
export class RequestLoggerPlugin implements DextoPlugin {
private logFilePath: string = '';
private logFileHandle: fs.FileHandle | null = null;
private requestCount: number = 0;
/**
* Initialize plugin - create log directory and open log file
*/
async initialize(config: Record<string, any>): Promise<void> {
// Default log path: ~/.dexto/logs/request-logger.log
const logDir = config.logDir || join(homedir(), '.dexto', 'logs');
const logFileName = config.logFileName || 'request-logger.log';
this.logFilePath = join(logDir, logFileName);
// Ensure log directory exists
await fs.mkdir(logDir, { recursive: true });
// Open log file in append mode
this.logFileHandle = await fs.open(this.logFilePath, 'a');
// Write initialization header
await this.writeLog('='.repeat(80));
await this.writeLog(`Request Logger initialized at ${new Date().toISOString()}`);
await this.writeLog(`Log file: ${this.logFilePath}`);
await this.writeLog('='.repeat(80));
}
/**
* Log user input before it's sent to the LLM
*/
async beforeLLMRequest(
payload: BeforeLLMRequestPayload,
context: PluginExecutionContext
): Promise<PluginResult> {
this.requestCount++;
await this.writeLog('');
await this.writeLog(`[${this.requestCount}] USER REQUEST at ${new Date().toISOString()}`);
await this.writeLog(`Session: ${payload.sessionId || 'unknown'}`);
await this.writeLog(`User: ${context.userId || 'anonymous'}`);
await this.writeLog(`Model: ${context.llmConfig.provider}/${context.llmConfig.model}`);
await this.writeLog('-'.repeat(40));
await this.writeLog(`Text: ${payload.text}`);
if (payload.imageData) {
await this.writeLog(
`Image: ${payload.imageData.mimeType} (${payload.imageData.image.length} chars)`
);
}
if (payload.fileData) {
await this.writeLog(
`File: ${payload.fileData.filename || 'unknown'} (${payload.fileData.mimeType})`
);
}
await this.writeLog('-'.repeat(40));
return { ok: true };
}
/**
* Log tool calls before execution
*/
async beforeToolCall(
payload: BeforeToolCallPayload,
context: PluginExecutionContext
): Promise<PluginResult> {
await this.writeLog('');
await this.writeLog(`[${this.requestCount}] TOOL CALL at ${new Date().toISOString()}`);
await this.writeLog(`Tool: ${payload.toolName}`);
await this.writeLog(`Call ID: ${payload.callId || 'unknown'}`);
await this.writeLog(`Arguments: ${JSON.stringify(payload.args, null, 2)}`);
return { ok: true };
}
/**
* Log tool results after execution
*/
async afterToolResult(
payload: AfterToolResultPayload,
context: PluginExecutionContext
): Promise<PluginResult> {
await this.writeLog('');
await this.writeLog(`[${this.requestCount}] TOOL RESULT at ${new Date().toISOString()}`);
await this.writeLog(`Tool: ${payload.toolName}`);
await this.writeLog(`Call ID: ${payload.callId || 'unknown'}`);
await this.writeLog(`Success: ${payload.success}`);
const resultStr =
typeof payload.result === 'string'
? payload.result.substring(0, 500) + (payload.result.length > 500 ? '...' : '')
: JSON.stringify(payload.result, null, 2).substring(0, 500);
await this.writeLog(`Result: ${resultStr}`);
return { ok: true };
}
/**
* Log assistant response before it's sent to the user
*/
async beforeResponse(
payload: BeforeResponsePayload,
context: PluginExecutionContext
): Promise<PluginResult> {
await this.writeLog('');
await this.writeLog(
`[${this.requestCount}] ASSISTANT RESPONSE at ${new Date().toISOString()}`
);
await this.writeLog(`Session: ${payload.sessionId || 'unknown'}`);
await this.writeLog(`Model: ${payload.provider}/${payload.model || 'unknown'}`);
if (payload.tokenUsage) {
await this.writeLog(
`Tokens: ${payload.tokenUsage.input} input, ${payload.tokenUsage.output} output`
);
}
await this.writeLog('-'.repeat(40));
await this.writeLog(`Content: ${payload.content}`);
if (payload.reasoning) {
await this.writeLog('-'.repeat(40));
await this.writeLog(`Reasoning: ${payload.reasoning}`);
}
await this.writeLog('-'.repeat(40));
return { ok: true };
}
/**
* Cleanup - close log file handle
*/
async cleanup(): Promise<void> {
await this.writeLog('');
await this.writeLog('='.repeat(80));
await this.writeLog(`Request Logger shutting down at ${new Date().toISOString()}`);
await this.writeLog(`Total requests logged: ${this.requestCount}`);
await this.writeLog('='.repeat(80));
if (this.logFileHandle) {
await this.logFileHandle.close();
this.logFileHandle = null;
}
}
/**
* Helper method to write to log file
*/
private async writeLog(message: string): Promise<void> {
if (this.logFileHandle) {
await this.logFileHandle.write(message + '\n');
}
}
}
// Export the plugin class directly for the plugin manager to instantiate
export default RequestLoggerPlugin;

Some files were not shown because too many files have changed in this diff Show More