Learn how AI agents work, by doing. Point your coding agent at the Cat and build whatever you imagine.
Pure Python - install it with uv, run it, and start talking to your Cat.
uv init --bare
uv add cheshire-cat-ai
uv run ccat # open http://localhost:1865Then pick a model, and you're ready to build your first agent.
Everything you build comes from a single from cat import .... Learn the whole
model in an afternoon - then open it up as far as you want to go.
A loop that reads the chat, calls tools, and answers. Subclass it, give it a prompt - that’s an agent.
from cat import Agent
class Poet(Agent):
slug = "poet"
name = "Poet"
description = "Answers every message in rhyme"
system_prompt = "You are a poet and talk in rhyme"A method on your agent. Type-hinted, docstringed - the LLM calls it by function calling.
from cat import Agent, tool
class SockSeller(Agent):
slug = "sock_seller"
system_prompt = "You sell socks talking in rhyme"
@tool
def socks_prices(self, color: str) -> str:
"""Get sock prices by color."""
prices = {"black": 5, "white": 10, "pink": 50}
return f"{prices.get(color, 0)} €"Middleware over the agent loop. RAG, memory, skills and guardrails are all just directives.
from datetime import datetime
from cat import Directive, Agent
class Clock(Directive):
slug = "clock"
name = "Clock"
async def step(self, agent: Agent) -> None:
now = datetime.now().strftime("%A %H:%M")
agent.system_prompt += f"\nThe time is {now}."
# use on any agent to inject time in system prompt
class Assistant(Agent):
slug = "assistant"
directives = ["clock"]React to lifecycle events with a one-argument function. Small, composable, easy to reason about.
from cat import hook
@hook
def before_agent_run(task):
# inspect or tweak every incoming task
task.messages.append(...)
@hook
def after_agent_run(result):
# ...and every outgoing reply
...Run many agents in one chat. Pick one per message, or let them call each other.
Connect Model Context Protocol servers - their tools, prompts and resources just work.
Tokens, tool calls and lifecycle events stream in real time over the AG-UI protocol.
OpenAI, Anthropic, Gemini, Ollama, OpenRouter, vLLM - swap with one line.
Drop a folder in and add agents, tools, directives and endpoints. No boilerplate.
A multi-chat, multi-agent interface waiting at localhost:1865 on first run.
Everything the Cat does is a plain Python package with an API - build on it by hand, or let a coding agent do it for you.
Expose a route with one decorator. Role-based auth is built in - no Depends plumbing.
POST /agents/{slug}/messagefrom cat import endpoint, user
@endpoint.get("/me", role="authenticated")
async def me():
return {"hi": user.name}Our growing and active community hosts many furrmidable events in the Discord server. Don't miss the chance to take part and save the dates!
