tanmay11k
34dea65a07
- mcp list/add/remove commands to manage MCP servers from any channel - skill list/show/create/remove/reload commands for skill management - skill create generates a SKILL.md template, or ask the AI naturally - Updated help text, commands.md with new commands - future-changes.md: WebChat UI overhaul plan (OpenClaw-inspired), MCP management UI, skill creator system, ClawHub/GitHub skill import plans
311 lines
13 KiB
Markdown
311 lines
13 KiB
Markdown
# Future Changes
|
|
|
|
Planned features and architectural improvements for Aetheel.
|
|
|
|
---
|
|
|
|
## Agent Teams & Delegation
|
|
|
|
The current subagent system spawns generic background workers that share the main agent's identity. The goal is to evolve this into a proper agent team architecture where specialized agents with their own roles, tools, and identity files can be created and coordinated.
|
|
|
|
### Vision
|
|
|
|
A main agent (e.g. "CTO") talks to the user and delegates tasks to specialist agents (e.g. "Programmer", "Designer") that each have their own personality, tool access, and domain expertise. Results flow back through the main agent or directly to the channel.
|
|
|
|
```
|
|
User ──► Main Agent (CTO)
|
|
│
|
|
├──► Programmer Agent
|
|
│ • Own SOUL.md (code-focused personality)
|
|
│ • Tools: Bash, Read, Write, Edit, Grep
|
|
│ • Model: claude-sonnet for speed
|
|
│
|
|
├──► Designer Agent
|
|
│ • Own SOUL.md (design-focused personality)
|
|
│ • Tools: WebSearch, WebFetch, Read
|
|
│ • Model: claude-opus for creativity
|
|
│
|
|
└──► Researcher Agent
|
|
• Own SOUL.md (thorough, citation-heavy)
|
|
• Tools: WebSearch, WebFetch
|
|
• Model: gemini-2.5-pro for large context
|
|
```
|
|
|
|
### What Exists Today
|
|
|
|
- `SubagentManager` spawns background tasks via `[ACTION:spawn|<task>]`
|
|
- `SubagentBus` provides pub/sub messaging between subagents
|
|
- Claude Code's `Task`, `TaskOutput`, `TeamCreate`, `SendMessage` tools are already in the allowed tools list
|
|
- All subagents currently share the same identity files (SOUL.md, USER.md, MEMORY.md)
|
|
|
|
### How NanoClaw Does It
|
|
|
|
NanoClaw (the inspiration project) takes a fundamentally different approach — container-based isolation with per-group identity:
|
|
|
|
**Architecture:**
|
|
- Each chat group gets its own folder (`groups/{name}/`) with its own `CLAUDE.md` (identity/memory)
|
|
- A `groups/global/CLAUDE.md` provides shared context readable by all groups
|
|
- Each agent runs inside an Apple Container (lightweight Linux VM) with only its own folder mounted
|
|
- The main channel has elevated privileges (can manage groups, write global memory, schedule tasks for any group)
|
|
- Non-main groups can only access their own folder + read-only global memory
|
|
|
|
**Agent Teams (Swarm):**
|
|
- Claude Code has native `TeamCreate`, `SendMessage` tools for multi-agent orchestration
|
|
- NanoClaw enables this via `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` env var in the container
|
|
- The lead agent creates teammates using Claude's built-in team tools
|
|
- Each teammate gets instructions to use `send_message` with a `sender` parameter
|
|
- On Telegram, each sender gets a dedicated bot identity (pool of pre-created bots renamed dynamically)
|
|
- The lead agent coordinates but doesn't relay every teammate message — users see them directly
|
|
|
|
**Key design decisions:**
|
|
- Identity is per-group, not per-agent — a "programmer" agent in one group is different from a "programmer" in another
|
|
- The AI itself decides when to create teams and how to structure them — it's not pre-configured
|
|
- Container isolation means agents can't read each other's files or sessions
|
|
- IPC is file-based (JSON files in a watched directory), not in-memory pub/sub
|
|
- Secrets are passed via stdin, never mounted as files
|
|
|
|
### What Needs to Be Built
|
|
|
|
#### 1. Agent Definitions
|
|
|
|
A new `agents/` directory in the workspace where each agent gets its own folder:
|
|
|
|
```
|
|
~/.aetheel/workspace/agents/
|
|
├── programmer/
|
|
│ ├── AGENT.md # Role, description, triggers
|
|
│ ├── SOUL.md # Agent-specific personality
|
|
│ └── SKILL.md # Optional: domain-specific skills
|
|
├── designer/
|
|
│ ├── AGENT.md
|
|
│ ├── SOUL.md
|
|
│ └── SKILL.md
|
|
└── researcher/
|
|
├── AGENT.md
|
|
└── SOUL.md
|
|
```
|
|
|
|
`AGENT.md` frontmatter:
|
|
|
|
```yaml
|
|
---
|
|
name: programmer
|
|
description: Senior software engineer specializing in Python and system design
|
|
triggers: [code, implement, build, fix, debug, refactor, PR]
|
|
model: anthropic/claude-sonnet-4-20250514
|
|
engine: claude
|
|
tools: [Bash, Read, Write, Edit, Glob, Grep]
|
|
max_turns: 5
|
|
---
|
|
```
|
|
|
|
#### 2. Agent-Aware Routing
|
|
|
|
The main agent decides which specialist to delegate to based on:
|
|
- Explicit user request ("ask the programmer to...")
|
|
- Trigger word matching from AGENT.md
|
|
- AI-driven routing (the main agent's system prompt tells it about available agents)
|
|
|
|
New action tag: `[ACTION:delegate|<agent_name>|<task>]`
|
|
|
|
#### 3. Per-Agent Identity
|
|
|
|
Each agent gets its own system prompt built from:
|
|
1. Its own `SOUL.md` (personality/role)
|
|
2. Shared `USER.md` (user context is universal)
|
|
3. Shared `MEMORY.md` (long-term memory is universal)
|
|
4. Its own skills from `SKILL.md`
|
|
5. Its tool restrictions from `AGENT.md`
|
|
|
|
#### 4. Agent-to-Agent Communication
|
|
|
|
Extend `SubagentBus` to support:
|
|
- Named channels per agent (not just task IDs)
|
|
- Request/response patterns (agent A asks agent B, waits for reply)
|
|
- Broadcast messages (main agent sends context to all agents)
|
|
- Result aggregation (main agent collects results from multiple agents)
|
|
|
|
#### 5. Team Orchestration Patterns
|
|
|
|
- **Sequential**: Programmer writes code → Designer reviews UI → Main agent summarizes
|
|
- **Parallel**: Programmer and Designer work simultaneously, main agent merges results
|
|
- **Supervisory**: Main agent reviews each agent's output before sending to user
|
|
- **Collaborative**: Agents can message each other directly via the bus
|
|
|
|
#### 6. Chat Commands
|
|
|
|
```
|
|
team list # List defined agents
|
|
team status # Show which agents are active
|
|
team create <name> # Interactive agent creation
|
|
team remove <name> # Remove an agent definition
|
|
delegate <agent> <task> # Manually delegate to a specific agent
|
|
```
|
|
|
|
#### 7. Claude Code Native Teams
|
|
|
|
Claude Code already has `TeamCreate`, `TeamDelete`, `SendMessage` tools. These allow the AI itself to create and manage teams during a session. The integration path:
|
|
|
|
- When using Claude Code engine, the AI can use these tools natively
|
|
- Aetheel wraps the results and routes messages back to the right channel
|
|
- Agent definitions in `AGENT.md` pre-configure teams that get created on startup
|
|
|
|
### Implementation Priority
|
|
|
|
There are two paths — pick based on complexity appetite:
|
|
|
|
**Path A: Lightweight (extend current SubagentManager)**
|
|
1. Agent definition format (`AGENT.md`) and discovery
|
|
2. Per-agent identity file loading (own SOUL.md, shared USER.md/MEMORY.md)
|
|
3. `[ACTION:delegate|agent|task]` tag parsing
|
|
4. Agent-specific system prompt building with tool restrictions
|
|
5. Chat commands for team management
|
|
6. Agent-to-agent communication via extended bus
|
|
|
|
**Path B: Full isolation (NanoClaw-style containers)**
|
|
1. Enable `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` for Claude Code runtime
|
|
2. Per-group workspace folders with own CLAUDE.md
|
|
3. Container-based agent execution (Docker or Apple Container)
|
|
4. File-based IPC between host and containers
|
|
5. Mount security (allowlist, per-group isolation)
|
|
6. Bot pool for Telegram/Discord (each agent gets its own bot identity)
|
|
7. Lead agent orchestration via Claude's native team tools
|
|
|
|
Path A is simpler and works today. Path B is more secure and scalable but requires container infrastructure.
|
|
|
|
### NanoClaw Reference Files
|
|
|
|
Key files to study in `inspirations/nanoclaw/`:
|
|
- `src/container-runner.ts` — Container spawning, volume mounts, IPC, per-group isolation
|
|
- `src/types.ts` — `RegisteredGroup`, `ContainerConfig`, `AdditionalMount` types
|
|
- `groups/global/CLAUDE.md` — Global identity shared across all groups
|
|
- `groups/main/CLAUDE.md` — Main channel with elevated privileges
|
|
- `.claude/skills/add-telegram-swarm/SKILL.md` — Full agent swarm implementation for Telegram
|
|
- `docs/SPEC.md` — Complete architecture spec
|
|
- `docs/SECURITY.md` — Security model for container isolation
|
|
|
|
---
|
|
|
|
## Other Planned Changes
|
|
|
|
### WebChat UI Overhaul
|
|
|
|
The current chat.html is a minimal single-file UI. Upgrade to match OpenClaw's design language:
|
|
|
|
**Design elements from OpenClaw to adopt:**
|
|
- Color palette: `--bg: #12141a`, `--card: #181b22`, `--accent: #ff5c5c` (or Aetheel's own brand color)
|
|
- Typography: Space Grotesk for body, JetBrains Mono for code
|
|
- Chat bubbles: user messages right-aligned with accent background, AI messages left-aligned with card background
|
|
- Streaming indicator: pulsing border on AI bubble while generating
|
|
- Tool cards: collapsible cards showing tool usage (web search, file ops, etc.)
|
|
- Compose area: multi-line textarea with send button, sticky at bottom
|
|
- Status bar: connection status, current engine/model display
|
|
|
|
**New panels (sidebar or tabs):**
|
|
- Settings panel: engine/model/provider switching, timeout config
|
|
- MCP Servers panel: add/remove/enable MCP servers
|
|
- Skills panel: view loaded skills, create new ones
|
|
- Usage panel: cost tracking, request history, rate limit status
|
|
- Sessions panel: active sessions, session history
|
|
|
|
### MCP Server Management
|
|
|
|
Add the ability to manage MCP servers from chat, CLI, and the WebChat UI.
|
|
|
|
**Chat commands:**
|
|
```
|
|
mcp list # List configured MCP servers
|
|
mcp add <name> <command> [args...] # Add a new MCP server
|
|
mcp remove <name> # Remove an MCP server
|
|
mcp enable <name> # Enable a disabled server
|
|
mcp disable <name> # Disable without removing
|
|
```
|
|
|
|
**Examples:**
|
|
```
|
|
mcp add brave-search uvx brave-search-mcp@latest
|
|
mcp add filesystem npx @anthropic-ai/mcp-filesystem /home/user/projects
|
|
mcp add github uvx github-mcp-server
|
|
mcp remove brave-search
|
|
```
|
|
|
|
**Implementation:**
|
|
- Chat commands write to `config.json` → `mcp.servers` section
|
|
- `write_mcp_config()` already generates `.mcp.json` (Claude) or `opencode.json` (OpenCode)
|
|
- After adding/removing, auto-call `write_mcp_config()` and notify user to reload
|
|
- WebChat UI: form with name, command, args fields + env vars
|
|
- CLI: `aetheel mcp add/remove/list` subcommands
|
|
|
|
**Popular MCP servers to suggest during setup:**
|
|
- `brave-search` — Web search
|
|
- `filesystem` — File system access
|
|
- `github` — GitHub API
|
|
- `postgres` / `sqlite` — Database access
|
|
- `puppeteer` — Browser automation
|
|
- `memory` — Persistent memory server
|
|
|
|
### Skills System Enhancement
|
|
|
|
#### Skill Creator (via chat)
|
|
|
|
The AI should be able to create new skills when asked. This works by having the AI write a `SKILL.md` file to the workspace.
|
|
|
|
**How it works today:**
|
|
- The system prompt already tells the AI: "You can create new skills by writing SKILL.md files to ~/.aetheel/workspace/skills/<name>/SKILL.md"
|
|
- The AI has file write access via its runtime tools (Bash, Write, Edit)
|
|
- So skill creation via natural language already works — just ask: "Create a skill for checking weather"
|
|
|
|
**What to add:**
|
|
- A `skill` chat command for explicit management:
|
|
```
|
|
skill list # List all loaded skills
|
|
skill create <name> # Interactive skill creation wizard
|
|
skill remove <name> # Remove a skill
|
|
skill reload # Reload all skills (same as /reload)
|
|
skill show <name> # Show a skill's SKILL.md content
|
|
```
|
|
- Skill templates: pre-built SKILL.md templates for common use cases
|
|
- Skill import from URL: `skill import https://github.com/user/repo/SKILL.md`
|
|
|
|
#### ClawhHub / Community Skills
|
|
|
|
Integration with external skill sources:
|
|
|
|
- **ClawHub.ai**: If they provide an API or registry, add `skill search <query>` and `skill install <name>` commands
|
|
- **GitHub Anthropic skills**: Import from `github.com/anthropics/claude-code/tree/main/skills/`
|
|
- **User-defined skill repos**: `skill import <git-url>` clones a repo's skills into the workspace
|
|
|
|
**Implementation:**
|
|
```
|
|
skill search weather # Search ClawHub/GitHub for skills
|
|
skill install clawhub/weather # Install from ClawHub
|
|
skill import https://github.com/user/skills-repo # Import from git
|
|
```
|
|
|
|
Each imported skill gets its own folder under `~/.aetheel/workspace/skills/<name>/` with a `SKILL.md` and optionally a `handler.py`.
|
|
|
|
### Security Fixes (from security-audit.md)
|
|
|
|
- Path containment check in `memory/manager.py` `read_file()`
|
|
- Mandatory webhook auth when enabled
|
|
- Input schema validation on webhook POST bodies
|
|
- Stricter cron expression validation
|
|
- Rate limiting on HTTP endpoints
|
|
- WebSocket authentication for WebChat
|
|
- Dependency version pinning
|
|
|
|
### Persistent Usage Stats
|
|
|
|
Currently usage stats reset on restart. Persist to SQLite so `usage` command shows lifetime stats, daily/weekly/monthly breakdowns, and cost trends.
|
|
|
|
### Multi-Model Routing
|
|
|
|
Route different types of requests to different models automatically:
|
|
- Quick questions → fast/cheap model (sonnet, gpt-4o-mini)
|
|
- Complex reasoning → powerful model (opus, o1)
|
|
- Large context → big-context model (gemini-2.5-pro)
|
|
|
|
### Conversation Branching
|
|
|
|
Allow users to fork a conversation into a new thread with a different model or agent, then merge results back.
|