TrinityClaw/trinity-claw

title: TrinityClaw AI Agent
emoji: 🦾
colorFrom: purple
colorTo: blue
sdk: docker
pinned: false
---
TrinityClaw AI Agent
A self-modifying AI agent with persistent memory, dynamic skill creation, and intelligent reasoning capabilities.
---
> ## 🖥️ LOCAL USE ONLY
>
> **TrinityClaw is designed for personal local servers — do not deploy it on a VPS or any public-facing server.**
>
> The agent API has no rate limiting and no multi-user authentication layer. The code_executor and terminal skills run arbitrary code inside Docker, and the single TRINITY_API_KEY is not sufficient protection for an internet-exposed host. Running this on a public IP without additional firewall rules and a reverse proxy with proper auth could expose your system to unauthorized access.
>
> **Recommended setup:** run on your home machine or a local network server, accessed via your LAN or a private VPN (e.g. Tailscale, WireGuard). Do **not** open ports 8001, 8080, or 8090 to the public internet.
https://github.com/user-attachments/assets/8ef1ddcf-b816-4566-87af-ce6511ed52fd
---
⚠️ Security Notice
TrinityClaw is **secure by design** in its original form:
- All skills run inside an isolated Docker container with no host access
- Dynamic skill creation uses AST validation and a module ban-list to block dangerous code
- The agent API is protected by a randomly-generated TRINITY_API_KEY
- Telegram integration only responds to your specific Chat ID
- Core skills are read-only inside the container; only skills/dynamic/ is writable by the agent
However, **any modification to the codebase can introduce risk.** This is an inherent property of self-modifying AI agent systems:
- Editing core skills, relaxing the module ban-list, or adding new file-system access can expand the attack surface
- Prompt injection via untrusted web content or external data sources is a known risk class for all LLM agents
- Credentials in .env (API keys, SMTP passwords, Telegram tokens) should be treated as sensitive — never commit .env to a public repository
- The code_executor and terminal skills run code inside the container — review any AI-generated code before executing it on sensitive systems
- Dynamic skills created by the agent should be inspected before being promoted to skills/core/
This project follows responsible AI agent design practices, but **no system is unconditionally safe once modified.** If you extend or customize TrinityClaw, you take on responsibility for auditing those changes.
---
Features
- **Self-Modifying**: Creates new skills dynamically
- **Persistent Memory**: ChromaDB vector storage + JSONL logs, daily journaling, goal tracking, and weekly meta-review synthesis across all memory files
- **Multi-Step Reasoning**: Agent loop for complex tasks
- **Dynamic Skills**: Core system skills + user-created skills
- **Web Browsing**: Fetch and analyze web content, including JS-rendered pages
- **Browser Automation**: Full Playwright-powered browser control — navigate, click, type, screenshot, evaluate JS, fill forms
- **Live Browser Session**: Attach to your existing logged-in Chrome via CDP — post to Twitter/X, LinkedIn, Instagram, and any platform directly from the agent using your real sessions, no API keys required
- **MCP Client (Model Context Protocol)**: Connect to remote and local MCP servers — discover, test, filter, and call their tools; connected tools become first-class agent skills automatically
- **Composio Integration**: Connect to 200+ apps (Slack, Notion, Jira, Stripe, HubSpot and more) with OAuth handled automatically
- **Scheduler**: Run automated tasks
- **Telegram Integration**: Chat with your agent via text, voice messages, and photos
- **Google Calendar**: Read, create, update, and delete calendar events — just ask naturally
- **Gmail Integration**: Read inbox, search emails, download attachments, mark as read — full Gmail API access
- **Business Knowledge Base**: Drop your documents into a folder and the agent learns from them — meeting notes, SOPs, contracts, spreadsheets
- **Voice Messages**: Send audio to Telegram or web UI — transcribed locally via Whisper (no API key needed)
- **Image Vision & OCR**: Send photos via Telegram or web UI — described by a vision-capable LLM; local OCR (Tesseract) extracts text from screenshots, documents, and receipts in English, Italian, Spanish, French, Greek, and Serbian (Cyrillic + Latin)
- **Secure**: AST validation, skill whitelisting, Docker isolation
---
Quick Start
Prerequisites
- **Docker Desktop** (the only prerequisite — it's free): https://www.docker.com/products/docker-desktop/