SkillAgentSearch skills...

Griffin

Griffin: open-source, self-hosted platform for your own team of AI agents. Define agents with tools and per-caller permissions, delegate between them, and run on Claude, Cursor or any OpenAI-compatible model. Telegram, MCP, scheduled jobs.

Install / Use

claude mcp add paziresh24 -- npx -y github:paziresh24/Griffin

If the server publishes to npm under a different name, use that package instead β€” check the repo README.

About this skill
πŸ”Œ

MCP Server

Model Context Protocol server

Quality Score

84/100

Supported Platforms

Claude Code
Claude Desktop
Cursor

Tags

Our assessment of Griffin

Griffin scores 84/100 on our quality scale, 633rd of 950 AI & Machine Learning skills we index.

Its MCP Server is 14 KB long, well organised into 12 sections with 7 code examples: a thorough specification that gives an agent plenty to work with.

It has 10 GitHub stars, so there is little community track record yet; judge it on its content.

Substance
30/30
Structure
20/20
Description
15/15
Adoption
4/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated today, so Griffin is actively maintained.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 97/100, with no cautions. These come from repository metadata, not a code audit β€” read the skill file before letting an agent act on it.

Griffin compared with similar skills

All 4 of these similar skills score higher than Griffin; compare them before choosing.

SkillScoreStarsUpdatedFormat
Griffin (this skill)by paziresh248410todayMCP Server
claude-memby thedotmack100117.6ktodayCLAUDE.md
Agent-Reachby Panniantong100112.3k9d agoCLAUDE.md
Understand-Anythingby Egonex-AI10092.8k1d agoCLAUDE.md
rufloby ruvnet10081.9ktodayCLAUDE.md

Frequently asked questions

How do I install Griffin?
Run claude mcp add paziresh24 -- npx -y github:paziresh24/Griffin. The install tabs above show the steps for each supported agent.
Which AI agents does Griffin work with?
It is written for Claude Code, Claude Desktop and Cursor, as a MCP Server file. Other agents that read the same format can often use it too.
Is Griffin safe to use?
It is MIT-licensed and scores 97/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is Griffin still maintained?
The repository was last updated today, so Griffin is actively maintained.
<img src="docs/media/griffin-mark.svg" width="76" alt="">

Griffin β€” your own team of AI agents

GitHub stars CI License: MIT Release Website

A self-hosted shell for a small team of AI agents that work for you. You make the agents β€” what each one is, what it may touch, who may ask it β€” and they answer from typed tools instead of from the model's memory. Use it as a personal assistant on Telegram, a research or writing helper, an assistant your colleagues can message, an MCP backend for Claude Code, or an operations agent wired to your own systems β€” on Claude, Cursor or any OpenAI-compatible model, including local ones.

Node 24 Β· Cursor, Claude Agent SDK or any OpenAI-compatible API Β· SQLite Β· no SaaS control plane Β· MIT

Website: griffin.paziresh24.com · Use cases · Self-hosted AI agents · Telegram AI assistant · MCP server · فارسی

<picture> <source media="(prefers-color-scheme: dark)" srcset="docs/media/demo-dark.gif"> <img src="docs/media/demo-light.gif" width="720" alt="Griffin in Telegram: the orchestrator delegates to a researcher and a writer, asks for approval to create a weekly job, then delivers the report with a chart"> </picture>

Two minutes to your own

On a Linux server β€” one command checks the machine, installs Docker if it is missing, pulls the image and starts Griffin:

curl -fsSL https://griffin.paziresh24.com/install.sh | bash

It prints the address to open and how to read the login token. Run the same line again to update: the new version replaces the old one only once it is healthy, and your data stays in Docker volumes. Options go before bash (curl … | GRIFFIN_PORT=3200 GRIFFIN_PROXY=http://host:port bash); see the top of docs/install.sh for all of them.

With Docker you already have β€” one line, no clone, no key needed up front:

docker run -d --name griffin --restart unless-stopped -p 3100:3100 -v griffin-data:/data -v griffin-workspace:/workspace \
  ghcr.io/paziresh24/griffin:latest
docker exec griffin cat /data/owner.token   # the token you log in with

Open http://127.0.0.1:3100, log in, and the setup wizard walks you through it: pick an engine (Claude subscription token from claude setup-token, Anthropic API key, OpenAI, OpenRouter, a local Ollama, any OpenAI-compatible endpoint, or Cursor), paste the key, and it is tested with a real call on the spot β€” a rejected key, a region block, a network problem or an empty balance each say so in plain words. Then name your assistant and, if you like, connect a Telegram or Bale bot.

Prefer env? -e ANTHROPIC_API_KEY=… (an sk-ant-oat… subscription token works too), -e OPENAI_API_KEY=… with -e GRIFFIN_OPENAI_BASE_URL=…, or -e CURSOR_API_KEY=…. Behind a firewall or in a blocked region, set an outgoing proxy in the wizard (or -e GRIFFIN_PROXY=http://host:port). For Ollama on the same machine add --add-host=host.docker.internal:host-gateway. No key yet? -e GRIFFIN_DEMO=1 runs a scripted demo.

From source:

git clone https://github.com/paziresh24/Griffin.git griffin && cd griffin
npm ci && npm run build

mkdir -p data workspace
echo "sk-ant-…" > data/anthropic.api-key && chmod 600 data/anthropic.api-key   # or openai.api-key / cursor.api-key
GRIFFIN_DATA=./data GRIFFIN_WORKSPACE=./workspace PORT=3100 node apps/server/src/index.mjs

Open http://127.0.0.1:3100, log in with the token at data/owner.token, and start talking to the agent that is already there (no key file? the setup wizard opens first). No cluster, no vault, no YAML: a fresh install is a chat with one agent, and everything else is something you add when you want it.

Or stay in the terminal:

node bin/griffin.mjs "summarise what I asked you this week"   # streams the answer
node bin/griffin.mjs -i                                       # keep the chat open
node bin/griffin.mjs agents                                   # who exists, what they may use

docker compose -f deploy/compose.yaml up -d --build builds and runs the same thing from source.

To look around before wiring anything up, GRIFFIN_DEMO=1 GRIFFIN_AUTH=off … replaces the model with a scripted stand-in β€” the screenshots on this page are that demo.

It checks and repairs itself

Settings β†’ Health runs a live check: every engine gets a real call (and the reason it fails), agents sitting on an engine that does not answer, recent runs that failed or came back empty, stuck runs, messenger connections, disk space and the last server errors β€” each with a one-click fix and the wizard that sets it right. Every 15 minutes the same check repairs what is safe on its own: an agent whose engine rejects its key or is region-blocked moves to an engine that answers, and moves back once its own engine heals; stuck runs are stopped. The assistant has the same check as tools (self_check, self_fix), so "it does not work" is something you can ask it about. GRIFFIN_SELF_HEAL=off keeps the report and turns the automatic part off; node bin/griffin.mjs doctor prints the report in a terminal.

Make an agent

#/agents β†’ Ψ§ΫŒΨ¬Ω†Ψͺ جدید: an id, a name, one line about its job, and its instructions. Then switch on the tools it may use, and say who may call it β€” the owner, another agent, a scheduled job, a colleague on a messenger, or an external agent over MCP β€” and which of its tools each of them gets.

Agents are rows in a table, not code. Quotas are enforced where tools are handed to the model, so a tool a caller was not given does not exist for that run. docs/agents.md explains the model; examples/agents/ has profiles you can import as a starting point (a personal assistant, a writer, a researcher that only reads β€” and, if you run servers, a platform agent and two CDN agents).

What you get

Agents that delegate. delegate returns immediately and reports back when the subtask lands, so the agent you are talking to stays free; ask_agent is the short blocking variant. Each agent picks its own engine (Cursor, Claude, or any OpenAI-compatible endpoint) and model.

Charts and files in the conversation β€” the agent draws Vega-Lite from real rows, and images, video, PDF, Markdown and CSV render inline. The same chart goes to a messenger as an image.

<img src="docs/media/chart.png" width="900" alt="A memory usage chart drawn by the agent inside the chat, labelled as demo data">

Scheduled jobs β€” a prompt, a trigger and a delivery target; each run gets its own hidden chat, so a job that misbehaves leaves the same trace a person's chat would.

Messengers and other agents β€” Telegram/Bale bots and a Telegram account bridge; an MCP endpoint where another agent (Claude Code, for instance) connects with its own scoped token and gets task-shaped tools: send, wait, reply, cancel.

Threads with colleagues. On a Telegram account bridge, a colleague's DM opens a Griffin thread only when a small classifier says it is real work (thanks and small talk stay yours); the thread closes with the result, and messages that arrive while it works are answered together, once.

Rehearse before it talks to anyone. A simulation chat runs the whole delegation tree for real but records side effects instead of executing them; apps/server/scripts/eval.mjs replays scenarios against it and checks the answers.

No interface, when that is better. The core is the product; the UI is one client of it. There is a terminal client, a Bearer-authenticated HTTP API, MCP for other agents, messengers, and scheduled jobs that deliver where you already are β€” and GRIFFIN_WEB=off runs the whole thing headless. See docs/interfaces.md.

Tools for your own systems, if you want them. A separate broker process holds credentials and exposes typed tools. The packs that ship today are operational β€” Kubernetes (status, get, logs, in-pod df, secrets, CNPG), Prometheus and Grafana, PostgreSQL, S3, GitLab, MikroTik routers, ArvanCloud and NSIN CDNs, DNS/HTTP/TLS probes β€” and a new pack is one module with a schema. Each pack appears only once you configure what it needs, so an agent never sees a tool that cannot work.

The UI speaks English and Persian (right-to-left), picked from your browser and switchable in Settings.

Use it as an MCP server

Griffin is also an MCP server: Claude Code, Claude Desktop, Cursor or any other MCP client can hand it a task and follow it to the end (griffin_send, griffin_wait, griffin_reply, griffin_cancel, griffin_tasks, griffin_limits). Each client gets its own scoped token from #/peers.

# streamable HTTP (Claude Code)
claude mcp add --transport http griffin https://griffin.example.com/mcp --header "Authorization: Bearer grf_…"

For stdio-only clients, bin/griffin-mcp.mjs bridges stdio to the same endpoint and needs no npm install:

{ "mcpServers": { "griffin": { "command": "node", "args": ["/path/to/griffin/bin/griffin-mcp.mjs"],
  "env": { "GRIFFIN_URL": "https://griffin.example.com", "GRIFFIN_TOKEN": "grf_…" } } } }

How it fits together

browser Β· Telegram Β· MCP client
            β”‚
     β”Œβ”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
     β”‚ app     chats, agents, jobs,   β”‚  holds the model key
     β”‚         charts, files, MCP     β”‚  no infrastructure credentials, no shell
     β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
            β”‚ unix socket Β· typed JSON tools     (optional)
     β”Œβ”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
     β”‚ broker  kube Β· metrics Β· pg    β”‚  holds every credential
     β”‚         s3 Β· gitlab Β· routers  β”‚  guards enforced in code
     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  public API first, emergency SSH second

The split is the point: the process running the model holds no credential and has no shell, and the process that holds them exposes only named tools with schemas. More in docs/architecture.md.

Connect your own systems (optional)

  1. Copy config/site.example.json to config/site.json and describe your world: clusters and their emergency SSH paths, GitLab, object storage, routers, shell hosts.
  2. Put the credentials in a vault (OpenBao/Vault KV) β€” docs/configuration.md lists the item names the broker looks up.
  3. Start the broker: COMPOSE_PROFILES=tools docker compose -f deploy/compose.yaml up -d --build.
  4. In #/agents, switch the new tools on for the agent that should have them β€” or import examples/agents/platform.json and edit it.

This repository ships no environment. There are no hosts, clusters, tokens or organisation knowledge in it: unconfigured tools say "not configured" instead of guessing an endpoint, and the tests declare their own fixture site.

Layout

| Path | What | |---|---| | apps/server/ | Hono + SQLite + SSE, agent runtime, auth, jobs, incidents, MCP | | apps/broker/ | every credential, typed tools over a unix socket, guards in code | | apps/web/ | the UI (assistant-ui + streamdown, RTL, PWA) | | packages/timeline/ | folds stored events into messages (shared by server and

Truncated for display β€” read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars10
CategoryAI
Updated12h ago
Forks1

Languages

JavaScript

Trust signals

97/100

From repository metadata: license, adoption, age and documentation. Not a code audit β€” see the Safety scan above for what the skill file itself contains.

1 info
Griffin β€” MCP Server: Install & Safety Check | SkillAgent