tiger-agent
Advanced tools
Agentic Swarm AI Agent with persistent long-term memory, multi-provider LLM support, token management, self-learning, and Telegram bot integration — designed for 24/7 autonomous operation on Linux.
Made by AI Research Group, Department of Civil Engineering, KMUTT
swarm/architecture/*.yaml with orchestrator, agents, stages, and judgment matrixtasks/styles/*.yaml and can select which architecture file to use/architecture and /taskstyle commands so Telegram users can list/show/write YAML and switch default architecture./soul.md or ./ownskill.md already exist, Tiger now mirrors updates to them automatically while continuing to use DATA_DIR as the canonical sourceDATA_DIR files from optional legacy root mirrorsclawhub_install and clawhub_search now work correctly when installed via npm install -gtiger onboard skips providers with no key; any single provider is enough to start/limit Telegram command — set per-provider daily token limits from chat without restartingnpm install -g tiger-agent, no git clone neededtiger CLI — unified command: tiger onboard, tiger start, tiger telegram, tiger stop/api, /tokens, /limit — manage providers and usage from chat| Feature | Tiger | Generic AI Assistants |
|---|---|---|
| Memory | Persistent lifetime memory (Vector DB) | Forgets when session ends |
| Learning | Self-training every 12 hours | Static, never improves |
| Security | Audit logs + Encryption + Hardened perms | No audit trail |
| Channels | CLI + Telegram simultaneously | Single channel only |
| Execution | Chains multiple skills autonomously | Single command only |
| Dimension | Tiger v0.3.4 🐯 | OpenClaw 🔧 | NanoClaw 🪐 |
|---|---|---|---|
| Language | JS + Python | TypeScript | TypeScript |
| Platform | Linux + Docker | macOS/Linux/Win | macOS/Linux/Win |
| Install | npm install -g tiger-agent | npm install -g openclaw | git clone + Claude Code |
| LLM Providers | 5 (Kimi, Z.ai, MiniMax, Claude, Moonshot) | OpenAI + Claude | Claude only |
| Multi-provider Failover | ✅ Auto on 429/403 | ✅ | ❌ |
| Token Budgeting | ✅ Per-provider daily limits | ❌ | ❌ |
| Predefined Agents | ✅ Role-based, customizable via Markdown files | ✅ Built-in typed agents | ❌ User-defined only |
| Swarm Architecture | ✅ YAML configurable | ❌ | ❌ |
| Parallel Execution | ✅ Fault-tolerant min_success threshold | ✅ | ✅ |
| Judgment Matrix | ✅ Weighted criteria + review-revise loop | ❌ | ❌ |
| Task Resume | ✅ /task continue <id> | ❌ | ❌ |
| Crash Detection | ✅ 60s heartbeat; 5-min stale -> restart worker | ❌ | ✅ 5-min -> reclaim tasks |
| Container Isolation | ✅ Docker hardened (cap_drop: ALL, read-only FS) | Optional Docker | ✅ Docker default |
| Memory Persistence | ✅ Cross-session SQLite + 30-day backup | Session only | Team lifetime only |
| Self-learning | ✅ 12h reflection + 24h regeneration | ❌ | ❌ |
| Vector Retrieval | ✅ sqlite-vec / cosine fallback | ❌ | ❌ |
| Audit Logging | ✅ | ❌ | ❌ |
| Voice / Browser | ❌ / ❌ | ✅ / ✅ | ❌ / ❌ |
| Channel Coverage | Telegram, WhatsApp, CLI | All + iMessage + Teams | Most major |
| Core Strength | Cost control + YAML swarm + self-learning | Channel breadth + voice + sync A2A | Security + formal swarm lifecycle |
| Core Weakness | Linux-primary; no cross-task DAG | High complexity; app-layer security | Single-provider lock-in |
npm install -g tiger-agent
All config and runtime data is stored in ~/.tiger/ — nothing written to the npm global directory.
Run Tiger in a hardened container with:
node)cap_drop: [ALL])no-new-privilegesTIGER_HOME (/home/node/.tiger)Build image:
docker build -t tiger-agent:local .
Run CLI mode:
docker run --rm -it \
--env-file .env \
--read-only \
--tmpfs /tmp \
--security-opt no-new-privileges:true \
--cap-drop ALL \
-e TIGER_HOME=/home/node/.tiger \
-v tiger_home:/home/node/.tiger \
tiger-agent:local start
Run Telegram mode via Compose:
docker compose up -d
docker compose logs -f tiger
Default compose command is telegram. Change command: in docker-compose.yml if you want start instead.
npm, not npn)tiger onboard
If you cloned this repo and run locally (without global install), use:
npm run onboard
The wizard will ask for:
zai, claude)Config is saved to ~/.tiger/.env (mode 600).
MiniMax starter (quick setup):
# during onboard: choose active provider = minimax
tiger onboard
# local repo alternative
# npm run onboard
Set at least:
ACTIVE_PROVIDER=minimaxMINIMAX_API_KEY=...CLI chat:
tiger start
# local repo
npm run start
Exit with /exit or /quit.
Telegram bot (foreground):
tiger telegram
# local repo
npm run telegram
Use foreground mode only for testing/log watching in the current terminal session.
Telegram bot (background daemon):
tiger telegram --background # start
tiger status # check if running
tiger stop # stop
# local repo
npm run telegram:bg # start
npm run telegram:stop # stop
Recommended for daily use: run background mode so Tiger keeps running after you close the terminal.
Restart background bot (after editing .env in this repo):
cd /root/tiger
npm run telegram:stop
npm run telegram:bg
Logs: ~/.tiger/logs/telegram.out.log
| Mode | Command | Description |
|---|---|---|
| CLI | tiger start | Interactive terminal chat |
| Telegram | tiger telegram | Telegram bot (foreground) |
| Background | tiger telegram --background | 24/7 daemon with auto-restart |
| Stop | tiger stop | Stop background daemon |
| Status | tiger status | Check daemon status |
| Onboard | tiger onboard | Re-run setup wizard |
Background crash detection:
tiger onboard writes ~/.tiger/.env with all settings. You can re-run it at any time to update config.
| Wizard prompt | What it sets |
|---|---|
| Active provider | ACTIVE_PROVIDER |
| Fallback order | PROVIDER_ORDER |
| API keys | ZAI_API_KEY, CLAUDE_API_KEY, etc. |
| Telegram token | TELEGRAM_BOT_TOKEN |
| Token limits | ZAI_TOKEN_LIMIT, CLAUDE_TOKEN_LIMIT, etc. |
| Shell tool | ALLOW_SHELL |
| Skill install | ALLOW_SKILL_INSTALL |
Tip: You can also edit
~/.tiger/.envdirectly and restart the bot to apply changes.
| Variable | Default | Description |
|---|---|---|
ACTIVE_PROVIDER | — | Active LLM provider (kimi, zai, minimax, claude, moonshot) |
PROVIDER_ORDER | — | Fallback order, comma-separated |
TELEGRAM_BOT_TOKEN | — | Telegram bot token |
ALLOW_SHELL | false | Enable shell tool |
ALLOW_SKILL_INSTALL | false | Enable ClawHub skill install |
VECTOR_DB_PATH | ~/.tiger/db/memory.sqlite | SQLite vector DB path |
DATA_DIR | ~/.tiger/data | Canonical context files directory |
OWN_SKILL_UPDATE_HOURS | 24 | Hours between ownskill.md regenerations (min 1) |
SOUL_UPDATE_HOURS | 24 | Hours between soul.md regenerations (min 1) |
REFLECTION_UPDATE_HOURS | 12 | Hours between reflection cycles (min 1) |
MEMORY_INGEST_EVERY_TURNS | 2 | Ingest durable memory every N conversation turns |
MEMORY_INGEST_MIN_CHARS | 140 | Minimum combined chars in a turn to trigger memory ingest |
Config lives in ~/.tiger/.env after running tiger onboard.
Tiger supports 5 providers with automatic fallback and daily token limits.
| Provider | ID | Default Model | API Key Variable |
|---|---|---|---|
| Kimi Code | kimi | k2p5 | KIMI_CODE_API_KEY |
| Kimi Moonshot | moonshot | kimi-k1 | MOONSHOT_API_KEY |
| Z.ai (Zhipu) | zai | glm-4.7 | ZAI_API_KEY (format: id.secret) |
| MiniMax | minimax | MiniMax-M2.5 | MINIMAX_API_KEY |
| Claude (Anthropic) | claude | claude-sonnet-4-6 | CLAUDE_API_KEY |
.env ExampleACTIVE_PROVIDER=zai
PROVIDER_ORDER=zai,claude,kimi,minimax,moonshot
KIMI_CODE_API_KEY=<key>
ZAI_API_KEY=<key>
MINIMAX_API_KEY=<key>
CLAUDE_API_KEY=<key>
MOONSHOT_API_KEY=<key>
# Daily token limits per provider (0 = unlimited)
KIMI_TOKEN_LIMIT=100000
ZAI_TOKEN_LIMIT=100000
MINIMAX_TOKEN_LIMIT=100000
CLAUDE_TOKEN_LIMIT=500000
MOONSHOT_TOKEN_LIMIT=100000
# Provider request timeouts (ms)
KIMI_TIMEOUT_MS=120000
ZAI_TIMEOUT_MS=120000
# Swarm worker-step timeout (0 = no extra swarm timeout)
SWARM_AGENT_TIMEOUT_MS=120000
# Swarm only: on timeout/network/API error, retry via next provider
SWARM_ROUTE_ON_PROVIDER_ERROR=true
# Swarm execution resilience
SWARM_STEP_MAX_RETRIES=2
SWARM_CONTINUE_ON_ERROR=true
# Swarm task entry policy
SWARM_DEFAULT_FLOW=auto
SWARM_FIRST_AGENT_POLICY=auto
# Used only when SWARM_FIRST_AGENT_POLICY=fixed
SWARM_FIRST_AGENT=designer
ACTIVE_PROVIDER for all requestsPROVIDER_ORDER~/.tiger/db/token_usage.json)| Command | Description |
|---|---|
/api | Show all providers with token usage |
/api <id> | Switch active provider (e.g. /api claude) |
/tokens | Show today's token usage per provider |
/limit | Show daily token limits per provider |
/limit <provider> <n> | Set daily token limit (0 = unlimited, e.g. /limit zai 100000) |
/swarm | Show agent swarm status (ON/OFF) |
| `/swarm <on | off>` |
/status | Show swarm task queues (pending, in_progress, done, failed) |
/task | List swarm tasks across queues |
/task continue <task_id> | Resume a failed/stuck swarm task from the last failed agent |
/task retry <task_id> | Alias of /task continue <task_id> |
/task delete <task_id> | Delete a swarm task file from queue storage |
/agents | Show internal swarm agents and availability |
/cancel <task_id> | Cancel a swarm task |
/ask <agent> <question> | Ask a specific internal agent role directly |
/architecture | List swarm architecture YAML files |
/architecture show <file> | Show one architecture YAML file |
/architecture use <file> | Set default task-style architecture file |
/architecture write <file> + newline + yaml | Save architecture YAML from Telegram |
/taskstyle | List task-style YAML files |
/taskstyle show <file> | Show one task-style YAML file |
/taskstyle write <file> + newline + yaml | Save task-style YAML from Telegram |
/help | Show all commands |
/swarm)Tiger v0.3.4 includes an internal agent swarm for Telegram message routing.
SWARM_ENABLED=false)/swarm on: regular user messages are routed through the YAML architecture in swarm/architecture/*.yaml (selected by tasks/styles/default.yaml)/swarm off: regular user messages skip the swarm and go directly to the standard Tiger agent reply path/api, /tokens, /limit)/swarm toggle is currently in-memory only and resets to SWARM_ENABLED value after bot restart/task continue <task_id> (or /task retry <task_id>) to continue a failed timeout/API-error task without starting over.env)SWARM_AGENT_TIMEOUT_MS: timeout per swarm worker step (e.g. one designer turn). 0 disables the extra swarm timeout.SWARM_ENABLED=true|false: default /swarm state at bot startup.SWARM_ROUTE_ON_PROVIDER_ERROR=true|false: swarm-only provider failover on timeout/network/API errors.SWARM_STEP_MAX_RETRIES: retries per failed worker/stage before giving up.SWARM_CONTINUE_ON_ERROR=true|false: if true, swarm continues on degraded path after retries are exhausted (instead of hard failing).KIMI_TIMEOUT_MS, ZAI_TIMEOUT_MS, CLAUDE_TIMEOUT_MS..env)SWARM_DEFAULT_FLOW=auto|design|research_build: default flow for new Telegram swarm tasks.SWARM_FIRST_AGENT_POLICY controls who starts first:
auto (default): Tiger/orchestrator picks based on the goal textflow: use flow mapping (research_build -> scout, otherwise designer)fixed: use SWARM_FIRST_AGENTdesigner, scout, coder)SWARM_FIRST_AGENT is used when SWARM_FIRST_AGENT_POLICY=fixedExamples:
/swarm
/swarm off
/swarm on
/task
/task retry task_xxx
/task delete task_xxx
Tiger creates a local swarm workspace so you can manually customize each agent's behavior.
Default folders (project/runtime root):
agents/
tiger/
designer/
senior_eng/
spec_writer/
scout/
coder/
critic/
tasks/
pending/
in_progress/
done/
failed/
Each agent folder includes files such as:
soul.md — the agent's personality, rules, and mindsetownskill.md — what the agent is good at / preferred workflowexperience.json — learned lessons and task statsmemory.md — long-form notes/patternshuman.md — only for agents/tiger/ (user preferences)Manual setup / editing:
tiger telegram or tiger start) and Tiger will auto-create missing agents/ and tasks/ foldersagents/designer/soul.md or agents/senior_eng/soul.md manually/ask designer ... or normal swarm-routed messages)Example customization ideas:
designer more creative / visualsenior_eng stricter about security, error handling, and scalabilityspec_writer produce a specific document format your team usesDefault files:
swarm/architecture/tiger_parallel_design.yaml
tasks/styles/default.yaml
Default architecture behavior:
tigerdesigner_a, designer_b, designer_c (different souls/personalities)
designer_a: senior conservativedesigner_b: balanced, around 40 styledesigner_c: young aggressive, higher risk appetitereviewer evaluates with the judgment matrix and picks best candidatespec_writer writes final output in two sections: Calculation Report and Executive SummaryResilient execution behavior:
type: parallel now supports min_success (default 1) to define how many successful role outputs are required.<store_as>_errors.SWARM_STEP_MAX_RETRIES.SWARM_CONTINUE_ON_ERROR=true, swarm continues on a degraded path instead of hard fail.Example swarm/architecture/tiger_parallel_design.yaml:
version: 1
name: tiger_parallel_design
main_orchestrator: tiger
start_stage: design_parallel
agents:
- id: designer_a
runtime_agent: designer_a
role: designer
- id: designer_b
runtime_agent: designer_b
role: designer
- id: designer_c
runtime_agent: designer_c
role: designer
- id: reviewer
runtime_agent: senior_eng
role: reviewer
- id: spec_writer
runtime_agent: spec_writer
role: spec_writer
stages:
- id: design_parallel
type: parallel
roles:
- designer_a
- designer_b
- designer_c
min_success: 2
store_as: design_candidates
next: review_best
- id: review_best
type: judge
role: reviewer
candidates_from: design_candidates
selected_role_key: selected_role
feedback_key: reviewer_feedback
calculation_report_key: best_calculation_report
pass_next: final_spec
fail_next: revise_selected
- id: revise_selected
type: revise
role_from_context: selected_role
feedback_from_context: reviewer_feedback
candidates_from: design_candidates
update_context_keys_from_revised:
- best_calculation_report
next: review_best
- id: final_spec
type: final
role: spec_writer
source_from_context: best_calculation_report
output_sections:
- Calculation Report
- Executive Summary
output_notes: Include formulas, assumptions, step-by-step calculations, final values, and concise recommendations.
next: tiger_done
judgment_matrix:
criteria:
- name: objective_fit
weight: 0.35
description: How well the design satisfies the objective.
- name: feasibility
weight: 0.25
description: Delivery realism and technical viability.
- name: clarity
weight: 0.2
description: Readability and implementation clarity.
- name: risk
weight: 0.2
description: Risk exposure and mitigation quality.
pass_rule: reviewer_approval
Task style is the selector/policy layer for swarm execution.
architecture: which file in swarm/architecture/ to runflow: flow label for task routing modeobjective_prefix: text prepended to the user objective before processingDefault file:
tasks/styles/default.yaml
Example:
version: 1
name: default
architecture: tiger_parallel_design.yaml
flow: architecture
objective_prefix: "Objective:"
Loaded on every turn from DATA_DIR (default: ~/.tiger/data/):
| File | Purpose |
|---|---|
soul.md | Agent identity, principles, and stable preferences |
human.md | User profile — goals, patterns, preferences |
human2.md | Running update log written after every conversation turn |
ownskill.md | Known skills, workflows, and lessons learned |
v0.2.5 compatibility note: If root-level legacy files already exist (for example
./soul.md,./ownskill.md), Tiger mirrors updates to those files automatically. The canonical source remainsDATA_DIR.
Tiger periodically regenerates these files using the LLM. All durations are configurable in .env (minimum 1 hour).
| Cycle | .env Variable | Default | What It Does |
|---|---|---|---|
| Skill summary | OWN_SKILL_UPDATE_HOURS | 24 | Rewrites ownskill.md with updated skills, workflows, and lessons derived from recent conversations |
| Soul refresh | SOUL_UPDATE_HOURS | 24 | Rewrites soul.md to reflect any evolved identity, operating rules, or preferences |
| Reflection | REFLECTION_UPDATE_HOURS | 12 | Extracts long-term memory bullets from recent messages and appends them to soul.md, human.md, ownskill.md, and the vector DB |
| Memory ingest | MEMORY_INGEST_EVERY_TURNS | 2 | After every N conversation turns, distils durable preference or workflow facts into the vector DB |
Note: Refresh timers for
soul.mdandownskill.mdare tracked in the DB (not file modification time), so reflection appends do not reset the 24-hour clock.
Example .env — tighten cycles for an active bot:
OWN_SKILL_UPDATE_HOURS=12
SOUL_UPDATE_HOURS=12
REFLECTION_UPDATE_HOURS=6
MEMORY_INGEST_EVERY_TURNS=2
MEMORY_INGEST_MIN_CHARS=140
Stored in ~/.tiger/db/memory.sqlite. Optional sqlite-vec extension enables fast ANN search:
SQLITE_VEC_EXTENSION=/path/to/sqlite_vec
Without it, Tiger falls back to cosine similarity in Python — slower but fully functional.
| Category | Tools |
|---|---|
| Files | list_files, read_file, write_file |
| Shell | run_shell (requires ALLOW_SHELL=true) |
| Skills | list_skills, load_skill, clawhub_search, clawhub_install |
| Orchestration | run_sub_agents |
Tiger can search and install skills from ClawHub — a community registry of reusable agent skills. The clawhub CLI is bundled with Tiger, no separate install needed.
Enable skill install in ~/.tiger/.env:
ALLOW_SKILL_INSTALL=true
Then just ask Tiger in chat:
Search for a web search skill on clawhub
Install the web-search skill
Skills are installed to ~/.tiger/skills/ and loaded automatically on demand.
Note:
ALLOW_SKILL_INSTALL=truemust be set duringtiger onboardor added manually to~/.tiger/.env.
| Feature | Detail |
|---|---|
| Credential Storage | ~/.tiger/.env.secrets with mode 600 |
| Database Security | ~/.tiger/db/ with hardened permissions |
| Audit Logging | Sanitized skill logs at ~/.tiger/logs/audit.log |
| Auto Backup | Daily SQLite backups, 30-day retention |
| Secret Rotation | Built-in 90-day rotation reminders |
# Run from ~/.tiger after onboard
export SECRETS_PASSPHRASE='your-passphrase'
node $(npm root -g)/tiger-agent/scripts/encrypt-env.js \
--in .env.secrets --out .env.secrets.enc
rm .env.secrets
| Feature | Tiger 🐯 | OpenClaw 🔧 |
|---|---|---|
| Identity | Persistent AI persona | Skill marketplace |
| Memory | Text files + SQLite vector | Skill-based only |
| Self-Training | ✅ 12h auto-reflection | ❌ Manual only |
| Skill Orchestration | Multi-skill pipelines | Single execution |
| Context Retention | ✅ Cross-session | Session-only |
| Security | ✅ Encryption + audit logs | Basic |
| Installation | npm install -g tiger-agent | clawhub install |
| Issue | Solution |
|---|---|
| Bot stuck on one provider | /api <name> in Telegram to switch manually |
| Provider silently skipped | No API key set, or daily limit reached — check /tokens |
401 auth error | Wrong or missing API key |
403 quota error | Daily quota exhausted — auto-switches; raise *_TOKEN_LIMIT |
429 rate limit | Auto-switches to next provider in PROVIDER_ORDER |
| Z.ai auth fails | Key must be id.secret format (from Zhipu/BigModel console) |
| Telegram bot runs but does not respond | Ensure only one polling instance is running for the same bot token (stop old/global service copies) |
soul.md / ownskill.md look stale | Check DATA_DIR first (default ~/.tiger/data). In v0.2.5+, existing root legacy copies are mirrored automatically |
| Shell tool disabled | Set ALLOW_SHELL=true in ~/.tiger/.env |
| Stuck processes | pkill -f tiger-agent then restart |
| Reset token counters | Delete ~/.tiger/db/token_usage.json and restart |
All runtime data lives in ~/.tiger/:
~/.tiger/
├── .env # Settings
├── .env.secrets # API keys (mode 600)
├── data/ # Context files (soul.md, human.md, ...)
├── db/
│ ├── agent.json # Conversation state
│ ├── memory.sqlite # Vector memory
│ └── token_usage.json # Daily token counters
└── logs/
├── audit.log
└── telegram-supervisor.log
AI Research Group Department of Civil Engineering King Mongkut's University of Technology Thonburi (KMUTT) Bangkok, Thailand
[虎 - Hǔ - The Tiger: Powerful, agile, and relentless in pursuit of goals]
FAQs
Cognitive AI agent with persistent memory, multi-provider LLM, and Telegram bot
The npm package tiger-agent receives a total of 8 weekly downloads. As such, tiger-agent popularity was classified as not popular.
We found that tiger-agent demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.