🌍 English | 日本語 | 中文 | 한국어 | Español | Français | Italiano | Português | Deutsch
Version: 0.2.5 (CashClaw Edition)
___ ___ _ ___ ___ _ _ ___ ___ _
/ __|/ _ \ | \| \ \ / /_\ | \| |/ __/ _ \| |
| (_ | (_) | | .` |\ V / _ \| .` | (_| (_) |_|
\___|\___/ |_|\_| |_/_/ \_\_|\_|\___\___/(_)
/\_/\
( o.o )
> ^ < Secure AI Agent Framework
/| |\
(_| |_)
Secure, production-ready AI agent framework — A hardened fork of nanobot with enterprise-grade security, multi-agent collaboration, and advanced automation.
| Language | Description |
|---|---|
| 日本語 | セキュアなAIエージェント基盤。SSRF防御・4段階権限・マルチエージェント連携・ブラウザ自動操作・BM25+自己学習メモリ・案件自動検索を備えた、本番運用対応のフレームワーク。 |
| English | Secure AI agent framework with SSRF prevention, 4-tier permissions, multi-agent orchestration, browser automation, BM25+ self-learning memory, and automated job hunting — production-ready out of the box. |
| 中文（简体） | 安全的AI代理框架。具备SSRF防御、四级权限、多代理协作、浏览器自动化、BM25+自学习记忆、自动搜索项目等功能，开箱即用于生产环境。 |
| 한국어 | 보안 AI 에이전트 프레임워크. SSRF 방어, 4단계 권한, 멀티 에이전트 협업, 브라우저 자동화, BM25+ 자기학습 메모리, 자동 프로젝트 검색 기능을 갖춘 프로덕션 대응 프레임워크. |
| Category | Feature | Description |
|---|---|---|
| Security | SSRF Prevention | Domain whitelist + local IP blocking |
| Security | 4-Tier Permissions | READ_ONLY / TEST_WRITE / BROWSER_AUTO / FULL |
| Security | Dangerous Action Blocking | Auto-refuse delete/purchase/payment/admin |
| Security | Path Traversal Protection | Sanitized filenames + path validation |
| Security | Command Execution | Allowed dirs + audit logs + ~ expansion fix |
| Security | Cookie Security | Persistent storage + domain separation + 0o600 perms |
| Multi-Agent | tmux Messaging | send-keys with delivery confirmation & retry |
| Multi-Agent | Anti-Loop Protection | MD5 hashing + 10-second throttle |
| Multi-Agent | State Detection | Compacting/thinking/idle awareness |
| Multi-Agent | Custom MCP Servers | 5 specialized servers (denrei, browser, vision, memory, web-tools) |
| Browser | AX Tree Support | Full accessibility tree via Chrome DevTools Protocol |
| Browser | Vision Integration | Screenshot analysis + LLM-driven next action |
| Browser | Secure File Upload | Path validation + 20MB limit |
| Content | Content Repurpose | 1 text to X/note/Instagram/SEO blog auto-conversion |
| Content | Quality Validation | Platform checks + NG word detection + auto-fix |
| Content | YouTube Transcripts | Multi-language, 50KB limit, flexible URL formats |
| LLM | Failover Chains | Retry + fallback_providers |
| LLM | Error Classification | Rate limit/timeout/auth/server error detection |
| LLM | Qwen3.5 Thinking Fix | Direct Ollama native API bypass (think:false) |
| Memory | BM25+ Time-Decay Search | Pure Python BM25+ with 30-day half-life decay (no chromadb) |
| Learning | Self-Study Sessions | 3-mode rotation (feedback analysis / knowledge organization / integration report) |
| Learning | Feedback Accumulation | Feedback category for evaluator pipeline (v0.3.0) integration |
| Automation | CW Job Hunter | CrowdWorks scraping + skill matching + Slack notification |
| Automation | Scheduled Reports | Morning/evening summaries + anomaly detection |
| Automation | Health Checks | 3-hour error monitoring via cron |
Removed chromadb dependency entirely. Replaced with a pure Python BM25+ implementation featuring a 30-day half-life decay function. Older knowledge fades naturally, keeping the agent's memory relevant without manual pruning.
CashClaw-style autonomous learning. Rotates through 3 modes:
- Feedback Analysis — Reviews accumulated feedback, extracts actionable patterns
- Knowledge Organization — Consolidates scattered knowledge into structured categories
- Integration Report — Produces a synthesis of recent learnings
Runs automatically via cron every 6 hours.
New feedback category added to the memory system. Stores structured evaluations that connect directly to the evaluator pipeline planned for v0.3.0.
Automated CrowdWorks job search using Playwright. Scrapes listings, matches against configured skill profiles, and sends Slack notifications for relevant opportunities. Runs via cron every 2 hours.
nyancobot supports multiple messaging platforms out of the box. Install only what you need:
# Install specific platform
pip install nyancobot[slack] # Slack only
pip install nyancobot[discord] # Discord only
pip install nyancobot[line] # LINE only
pip install nyancobot[whatsapp] # WhatsApp only
# Install all messaging platforms
pip install nyancobot[all-channels]Slack: Get bot token from Slack API → Enable Socket Mode → Copy xoxb- and xapp- tokens.
Discord: Create bot at Discord Developer Portal → Copy token → Enable Message Content Intent.
LINE: Create channel at LINE Developers → Get Channel Access Token and Secret → Set webhook URL.
WhatsApp: Register at Meta for Developers → Get token and Phone Number ID → Configure webhook.
Update ~/.nyancobot/config/config.json:
{
"channels": {
"slack": {
"enabled": true,
"bot_token": "xoxb-YOUR-TOKEN",
"app_token": "xapp-YOUR-TOKEN",
"signing_secret": "YOUR_SECRET"
},
"discord": {
"enabled": true,
"token": "YOUR_DISCORD_BOT_TOKEN"
}
}
}- Python 3.10+
- Playwright browser binaries
# Install from PyPI (when published)
pip install nyancobot
# Or install from source
git clone https://github.com/asiokun/nyancobot.git
cd nyancobot
pip install -e .
# Install Playwright browsers
playwright install chromium- Create configuration file
mkdir -p ~/.nyancobot/config
cp config.example.json ~/.nyancobot/config/config.json- Set environment variables
export OPENAI_API_KEY="YOUR_API_KEY"
export ANTHROPIC_API_KEY="YOUR_API_KEY" # Optional
export OLLAMA_BASE_URL="http://localhost:11434" # Optional- Configure browser permission level
# Level 0: READ_ONLY (safe)
# Level 1: TEST_WRITE (test domains only)
# Level 2: BROWSER_AUTO (browser automation)
# Level 3: FULL (all actions)
echo "2" > ~/.nyancobot/config/permission_level.txt- Set allowed domains (for SSRF prevention)
cat > ~/.nyancobot/config/allowed_domains.txt <<EOF
example.com
httpbin.org
crowdworks.jp
lancers.jp
EOF- Run nyancobot
nyancobot{
"llm": {
"provider": "litellm",
"model": "gpt-4-turbo",
"fallback_providers": ["ollama/qwen2.5:32b"],
"temperature": 0.7,
"max_tokens": 4096
},
"browser": {
"headless": true,
"viewport": {"width": 1280, "height": 720},
"timeout": 30000
},
"security": {
"permission_level": 2,
"audit_log": "~/.nyancobot/audit.jsonl",
"allowed_dirs": ["~/projects", "/tmp"]
},
"mcp_servers": {
"denrei": {
"command": "python",
"args": ["~/.nyancobot/scripts/denrei-mcp-server.py"]
},
"browser": {
"command": "python",
"args": ["~/.nyancobot/scripts/browser-mcp-server.py"]
}
}
}| Variable | Description | Default |
|---|---|---|
OPENAI_API_KEY |
OpenAI API key (required) | - |
ANTHROPIC_API_KEY |
Anthropic API key (optional) | - |
OLLAMA_BASE_URL |
Ollama server URL (optional) | http://localhost:11434 |
NYANCOBOT_CONFIG |
Path to config.json | ~/.nyancobot/config/config.json |
NYANCOBOT_LOG_LEVEL |
Logging level | INFO |
┌─────────────────────────────────────────────────────────────┐
│ User / Scheduler │
└───────────────────────────┬─────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ nyancobot Agent Loop │
│ ┌────────────────────────────────────────────────────┐ │
│ │ LLM Provider (litellm + failover) │ │
│ │ - OpenAI / Anthropic / Ollama │ │
│ │ - Auto-retry / Fallback chains │ │
│ └────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ Security Layer (4-tier permissions) │ │
│ │ - SSRF prevention (domain whitelist) │ │
│ │ - Path traversal protection │ │
│ │ - Dangerous action blocking │ │
│ │ - Audit logging │ │
│ └────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ Tool Router │ │
│ │ ┌──────────┬──────────┬──────────┬─────────────┐ │ │
│ │ │ Browser │ Shell │ Denrei │ Content │ │ │
│ │ │ (secure) │ (secure) │ (multi- │ (repurpose) │ │ │
│ │ │ │ │ agent) │ │ │ │
│ │ └──────────┴──────────┴──────────┴─────────────┘ │ │
│ └────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ External Systems / MCP Servers │
│ - Slack (notifications) │
│ - Browser (Playwright) │
│ - Vision Secretary (screenshot analysis) │
│ - Memory Search (BM25+ time-decay) │
│ - Web Tools │
└─────────────────────────────────────────────────────────────┘
Agent A Agent B
│ │
│ send-keys (message) │
├─────────────────────────►│
│ │
│ ◄─ State check ─────────┤
│ (idle/busy?) │
│ │
│ ◄─ Delivery confirm ────┤
│ │
│ [Anti-loop check] │
│ (MD5 hash + throttle) │
│ │
│ ◄─ Response ────────────┤
│ │
- BM25+ Time-Decay Memory Search: Removed chromadb dependency. Pure Python BM25+ with 30-day half-life decay for natural knowledge aging.
- Self-Study Sessions (
self_study.py): CashClaw-style autonomous learning with 3-mode rotation (feedback analysis / knowledge organization / integration report). Cron every 6 hours. - Feedback Accumulation: New feedback category in memory system. Ready for evaluator pipeline (v0.3.0) integration.
- CW Job Hunter (
cw_job_hunter.py): CrowdWorks Playwright scraping + skill matching + Slack notification. Cron every 2 hours.
- browser_stealth integration: Enhanced anti-detection for browser automation.
- xai-search fix: Corrected search API integration issues.
- Initial release. Fork of nanobot with security hardening, multi-agent collaboration, and browser automation.
nyancobot is a fork of nanobot by HKUDS.
We are deeply grateful to the original nanobot team for their elegant and lightweight foundation.
See ATTRIBUTION.md for detailed credits and modifications.
MIT License - see LICENSE for details.
Dual Copyright:
- Original nanobot: Copyright (c) 2025 nanobot contributors
- nyancobot modifications: Copyright (c) 2026 nyancobot contributors
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Security Issues: Please report security vulnerabilities via GitHub Security Advisories (not public issues).
- Original nanobot: https://github.com/HKUDS/nanobot
- Documentation: [Coming soon]
- Issues: https://github.com/asiokun/nyancobot/issues
- Discussions: https://github.com/asiokun/nyancobot/discussions
- HKUDS for the original nanobot framework
- Playwright team for robust browser automation
- litellm for unified LLM provider interface
- FastMCP for MCP server infrastructure
- All contributors to the nyancobot project
Made with care by the nyancobot community