birdie-agent 0.5.1

Dynamic skill-based LangGraph agent

Birdie

      ___                       ___           ___                       ___     
    /\  \          ___        /\  \         /\  \          ___        /\  \    
   /::\  \        /\  \      /::\  \       /::\  \        /\  \      /::\  \   
  /:/\:\  \       \:\  \    /:/\:\  \     /:/\:\  \       \:\  \    /:/\:\  \  
 /::\~\:\__\      /::\__\  /::\~\:\  \   /:/  \:\__\      /::\__\  /::\~\:\  \ 
/:/\:\ \:|__|  __/:/\/__/ /:/\:\ \:\__\ /:/__/ \:|__|  __/:/\/__/ /:/\:\ \:\__\
\:\~\:\/:/  / /\/:/  /    \/_|::\/:/  / \:\  \ /:/  / /\/:/  /    \:\~\:\ \/__/
 \:\ \::/  /  \::/__/        |:|::/  /   \:\  /:/  /  \::/__/      \:\ \:\__\  
  \:\/:/  /    \:\__\        |:|\/__/     \:\/:/  /    \:\__\       \:\ \/__/  
   \::/__/      \/__/        |:|  |        \::/__/      \/__/        \:\__\    
    ~~                        \|__|         ~~                        \/__/    

A LangGraph-based agent that discovers capabilities at runtime from SKILL.MD and AGENT.MD files. Skills, tools, and sub-agents are all declared in plain Markdown - no code changes required to add new capabilities.

Birdie is a minimal yet fully functional implementation. The design goal is simplicity and transparency: the codebase is intended to be readable, hackable, and easy to extend. Every major feature - the agent loop, skill loading, session persistence, conversation compaction, long-term memory - is implemented in a small number of well-commented Python files that you can read from top to bottom in an afternoon.

Security notice: Birdie has no guardrails against local tool misuse. Skills such as Shell and Filesystem can read, write, and execute anything the running user is permitted to do. Only enable skills you trust and run Birdie under an account with appropriate restrictions.

---

---

Installation

From PyPI (recommended)

pip install birdie-agent

From source

git clone https://github.com/gkvas/birdie.git
cd birdie
pip install -e .

Optional extras

pip install "birdie-agent[mcp]"   # MCP server support
pip install -e ".[dev,mcp]"       # development + MCP (from source)

---

Quick start

Configure your LLM provider and run birdie.

Environment variables

# Anthropic
export LLM_VENDOR=anthropic
export LLM_MODEL=claude-sonnet-4-6
export ANTHROPIC_API_KEY=your-key-here
birdie

# OpenAI
export LLM_VENDOR=openai
export LLM_MODEL=gpt-4o
export OPENAI_API_KEY=your-key-here
birdie

# Mistral
export LLM_VENDOR=mistral
export LLM_MODEL=mistral-large-latest
export MISTRAL_API_KEY=your-key-here
birdie

#Azure OpenAI
export  LLM_VENDOR=azure
export LLM_MODEL=your-deployment-name
export AZURE_OPENAI_API_KEY=your-key-here
export AZURE_OPENAI_ENDPOINT=your-base-url
birdie

JSON config file

birdie --config ~/.birdie/provider.json

{
  "vendor": "anthropic",
  "model": "claude-sonnet-4-6",
  "api_key": "sk-ant-..."
}

See doc/cli.md for all supported vendors, config fields, and environment variable options.

---

Built-in skills

Skills extend Birdie and are defined in SKILL.MD files. All skills are disabled by default. Enable them for the current session:

/skill enable Shell
/skill enable DuckDuckGo

Birdie ships with the following default skills:

Skill	Description
Shell	Run arbitrary shell commands
Filesystem	Read and write local files
ssh	Connect to remote hosts and run commands
ToDo	Step-by-step planning and progress tracking
Weather	Weather lookup via external API
DuckDuckGo	Web search - no API key required
mcp_demo	Demo MCP server (echo and reverse_string)

See doc/skills.md for the full SKILL.MD format and how to write skills.

---

Sub-agents

Sub-agents are AI agents defined by AGENT.MD files. When enabled, a sub-agent appears to the calling LLM as a regular tool. Invoking it spins up an ephemeral agent, runs it to completion, and returns the result.

All agents are disabled by default. Enable them for the current session:

/agent enable Summarizer

Drop an AGENT.MD in ~/.birdie/agents/<name>/ to add custom sub-agents without reinstalling.

See doc/agents.md for the full AGENT.MD format and how to write custom agents.

---

Conversation memory

Birdie maintains three separate memory stores that work together to give the agent context across turns and sessions.

Short-term memory is handled automatically by LangGraph's SQLite checkpointer. Every message is stored in ~/.birdie/sessions/<user>/checkpoints.db and loaded at the start of each turn. The agent trims the loaded history to a 20-message context window before calling the LLM, so cost stays bounded even in very long sessions.

Manual long-term memory is written by you, explicitly. Use /remember to save any fact you want the agent to recall in future sessions:

/remember I prefer compact, direct answers without preamble
/remember The project uses Python 3.12 and pytest for tests

Notes are stored in ~/.birdie/sessions/<user>/memory.json and injected into the system prompt at the start of every turn, across all sessions.

Automatic long-term memory is written by the compaction pipeline. When a session grows beyond 100 messages, Birdie automatically summarises the oldest segment using the LLM, extracts structured facts, preferences, tool outcomes, and open tasks, and stores them in ~/.birdie/ltm/<user>.json. On future turns, the top-5 most semantically relevant entries are retrieved and injected alongside your manual /remember notes.

You can trigger compaction at any time with:

/compact

This is useful at the end of a long working session to capture everything important before starting fresh. The command displays the summary that was generated and how many messages were removed from the checkpoint.

The retrieval uses a lightweight hash-trick embedding (birdie/core/retrieval.py) that requires no model downloads or extra dependencies - just SHA-256 and a dot product.

See doc/architecture.md for a detailed explanation of how all three stores interact, how the compaction algorithm picks the split point, and how the LTM store is queried each turn.

---

Key commands

Command	Description
/skill list	List all skills and their status
/skill enable <name>	Enable a skill for this session
/agent list	List all sub-agents and their status
/agent enable <name>	Enable a sub-agent for this session
/agent output short|full|off	Control sub-agent transcript verbosity
/tool output short|full|off	Control tool result verbosity
/remember <text>	Save a note to long-term memory
/compact	Summarise old messages into long-term memory now
/session new	Start a new session
/session list	List all sessions
/help	Show all commands

---

Documentation

Document	Contents
doc/cli.md	CLI flags, provider config reference, all slash commands, key bindings
doc/skills.md	SKILL.MD format, entrypoints, tool and knowledge skills, skill loading
doc/agents.md	AGENT.MD format, sub-agent system, runtime controls, custom agents
doc/mcp.md	MCP integration, declaring MCP servers, writing MCP servers
doc/architecture.md	Project layout, agent loop, system prompt, providers, conversation compaction, long-term memory store, sessions

---

Running tests

pip install -e ".[dev,mcp]"
pytest