Firewood 🔥

An Open AI Assistant with Flame

A powerful, persistent AI assistant that works with multiple LLM providers, features universal function calling, real-time streaming responses, and an extensible skills system.

✨ Features

🤖 Multi-Provider Support (Unified Agent Architecture)

All providers use the OpenAI Agents SDK for unified tool calling and streaming:

OpenAI - GPT-4o, GPT-4 Turbo, o1, o3 series
Anthropic - Claude 3.5 Sonnet, Claude 3 Opus/Sonnet/Haiku
Kimi/Moonshot AI - kimi-k2.5 (latest), moonshot-v1 series
Custom APIs - Any OpenAI-compatible API endpoint (Ollama, vLLM, etc.)

🛠️ Universal Function Calling

Built-in functions that work with all providers:

Filesystem Functions - read_file, read_dir, write_file, append_file, delete_file, rename_fs, delete_dirs, create_dirs
HTTP Functions - http_get, http_post, http_put, http_patch, http_delete
Shell Functions - get_env, run_cmd for command execution
Token Functions - list_tokens for authentication token management
Skills Functions - load_skill for dynamic skill loading
Team Functions - intro_member, assign_tasks for team collaboration
Secure, configurable, and extensible

💾 Session Persistence

Automatic conversation saving
Resume sessions across restarts
Multiple concurrent sessions
Export to JSON
Session-specific provider configuration

🎭 Skills System

Extensible skills following Agent Skills specification
10 built-in skills: weather, git, github, gitea, makefile, backend_engineering, communication, project_management, system_design, system_test
Install from Git, local paths, or registries
Create custom skills for domain-specific workflows

👥 Team System

Role-based agent collaboration (TPM, Dev, Architect, QA)
Team member definitions with personalized configurations
Task assignment and member introduction functions

🌉 Bridge System

CLI Bridge - Terminal UI for human interaction (default)
GitHub Bridge - Automated GitHub Issues/PRs integration
Gitea Bridge - Gitea Issues/PRs integration
Feishu Bridge - Feishu/Lark chat integration
Daemon mode for background operation

🎨 Beautiful Terminal UI

Streaming responses with real-time display
Syntax highlighting
Auto-scrolling chat log
Keyboard shortcuts
Provider/model display
Powered by Textual

🔧 Flexible Configuration

Environment variables
TOML configuration files
System keyring (secure)
Interactive setup wizard with arrow key navigation

🚀 Quick Start

Installation

# Clone repository
git clone https://github.com/xflops/firewood
cd firewood

# Install dependencies (using uv - recommended)
uv sync

# Or using pip
pip install -e ".[all]"

Setup

# Run interactive setup wizard
firewood --setup

The setup wizard provides a beautiful, immersive full-screen experience:

🖥️ Takes over the entire terminal for a focused setup experience
📝 Step-by-step flow - One step at a time, no overwhelm
⚡ Auto-advance on Enter - Select option → press Enter → next step (automatic!)
🎯 Smart focus - Cursor always ready where you need it (no extra Tab presses)
💾 Smart defaults - Current config pre-loaded and highlighted
⏭️ Previous/Next navigation - Go back to change settings anytime
📊 Progress indicator - Always know where you are (Step X of 6)
✅ Real-time validation - Catches errors before moving forward
⌨️ Full keyboard navigation with arrow keys and Enter
🎨 Visual feedback as you configure each setting
🚀 Modern UI using Textual framework
⚡ 50% fewer keystrokes than traditional setup wizards

Configuration steps include:

Provider Selection - OpenAI, Anthropic, Kimi, or Custom (OpenAI-compatible)
API Key - Securely enter and mask your key
Model Selection - Choose from available models
Storage Options - Keyring, config file, or environment variable
Function Configuration - Enable/disable filesystem and HTTP access
Filesystem Mode - Read-only or read/write access

This will:

Prompt for your LLM provider (OpenAI, Anthropic, Kimi/Moonshot, Custom)
Request your API key
Select your preferred model
Configure function calling (filesystem, HTTP, shell)
Offer to store settings securely
Validate the configuration

Start Chatting

# Start with default settings
firewood

# Or specify provider and model
firewood --provider openai
firewood --provider kimi
firewood --provider anthropic
firewood --provider custom

📖 Usage

Basic Commands

# Start new session
firewood --new

# Resume specific session
firewood --session <session-id>

# List all sessions
firewood --list-sessions

# Show session details and messages
firewood --show-session <session-id>

# Show session with all Flame task details
firewood --show-session <session-id> --full

# Limit lines per message in show-session output
firewood --show-session <session-id> --max-lines 50

# Export session with decoded Flame tasks
firewood --show-session <session-id> --export-tasks tasks.json

# Show configuration
firewood --show-config

# Export session
firewood --export --session <session-id> --output backup.json

# Clean old sessions (30+ days)
firewood --clean-sessions

# Show recent logs
firewood --show-logs

# Run with verbose logging
firewood -v

# List installed skills
firewood --list-skills

# Show skill details
firewood --show-skill <skill-id>

Team Commands

# List discovered roles
firewood --list-roles

# List team members
firewood --list-members

# Show role specification
firewood --show-role <role-name>

# Show member introduction
firewood --show-member <member-name>

Bridge Commands

# Run GitHub bridge
firewood --bridge github

# Run Gitea bridge
firewood --bridge gitea

# Run Feishu bridge
firewood --bridge feishu

# Run bridge as daemon
firewood --bridge github --daemon

# Stop bridge daemon
firewood --stop-bridge

# Show bridge status
firewood --show-bridge-status

# List configured bridges
firewood --list-bridges

# Debug specific issues
firewood --bridge github --debug-issues 123,456

# Clean up Flame application used by bridges
firewood --clean-bridge-app

Keyboard Shortcuts (In Chat)

Enter - Send message
Ctrl+C - Quit and save
Ctrl+N - New session
Ctrl+S - Save session

Function Calling Examples

Firewood includes built-in functions that work with all LLM providers:

Filesystem Functions

You: Read my config.toml file

Firewood: [reads ~/.firewood/config.toml and shows contents]

You: Create a shopping list in shopping.txt with 5 items

Firewood: [writes file using write_file function]

HTTP Functions

You: Get the current weather from https://api.weather.com/current

Firewood: [makes HTTP GET request and returns data]

You: Post {"name": "test"} to https://httpbin.org/post

Firewood: [makes HTTP POST request with JSON payload]

Shell Functions

You: What's my OPENAI_API_KEY environment variable?

Firewood: [retrieves environment variable securely]

You: Run git status in the current directory

Firewood: [executes git status via run_cmd function]

Skills

You: What's the weather in San Francisco?

Firewood: [uses weather skill to fetch and display weather data]

Configuration

Config File Location

~/.firewood/config.toml

Example Configuration

[provider]
provider = "openai"
model = "gpt-4"

[functions]
enabled = true

[functions.filesystem]
base_path = "~/"
read_only = false
allowed_paths = ["~/"]

[functions.http]
timeout = 30
allowed_domains = [
    "*.example.com",
    "api.trusted-service.com"
]

[skills]
enabled = true
directory = "~/.firewood/skills"
global_skills = []

Environment Variables

# Provider-specific API keys
export OPENAI_API_KEY='sk-...'
export ANTHROPIC_API_KEY='sk-ant-...'
export KIMI_API_KEY='sk-...'
export CUSTOM_API_KEY='your-key'

# Skills directory
export FIREWOOD_SKILLS_DIR='~/.firewood/skills'

# Logging
export FIREWOOD_LOG_LEVEL='DEBUG'

🔧 Function Calling

Built-in Functions

Filesystem Functions

Function	Description	Parameters	Mode
`read_file`	Read file contents	`path`, `encoding`	Always
`read_dir`	List directory contents	`path`	Always
`write_file`	Write/create file	`path`, `content`, `encoding`, `create_dirs`	Write
`append_file`	Append to file	`path`, `content`, `encoding`	Write
`delete_file`	Delete a file	`path`	Write
`rename_fs`	Rename/move file or directory	`src`, `dst`	Write
`delete_dirs`	Delete directory recursively	`path`	Write
`create_dirs`	Create directories	`path`	Write

Security Features:

Path validation (no directory traversal)
Configurable base path
Read-only mode option
Allowed paths whitelist

HTTP Functions

Function	Description	Parameters
`http_get`	HTTP GET request	`url`, `headers`, `timeout`, `token_name`
`http_post`	HTTP POST request	`url`, `body`, `json_body`, `headers`, `timeout`, `token_name`
`http_put`	HTTP PUT request	`url`, `body`, `json_body`, `headers`, `timeout`, `token_name`
`http_patch`	HTTP PATCH request	`url`, `body`, `json_body`, `headers`, `timeout`, `token_name`
`http_delete`	HTTP DELETE request	`url`, `headers`, `timeout`, `token_name`

Security Features:

URL validation (http/https only)
Domain whitelisting (optional)
Configurable timeouts
Token-based authentication support
Safe error handling

Shell Functions

Function	Description	Parameters
`get_env`	Get environment variable	`name`, `default`
`run_cmd`	Run shell command	`command`, `cwd`, `timeout`, `env`, `token_name`

Security Features:

Workspace-constrained execution
Configurable timeouts
Token-based git authentication
Safe environment variable retrieval

Token Functions

Function	Description	Parameters
`list_tokens`	List available auth tokens	None

Skills Functions

Function	Description	Parameters
`load_skill`	Load skill file	`name`, `path`

Team Functions

Function	Description	Parameters
`intro_member`	Get team member introduction	`name`
`assign_tasks`	Assign tasks to team members (parallel)	`assignments` (array of {name, task})

How It Works

Registration - Functions are registered with FunctionManager on startup
Schema Generation - Function schemas are sent to the LLM
LLM Decision - The model decides when to call functions
Execution - FunctionManager executes the function securely
Result - Result is sent back to the LLM for final response
Streaming - All responses are streamed in real-time for better UX

Works with all providers: OpenAI, Anthropic, Kimi/Moonshot, and Custom APIs!

📁 Project Structure

firewood/
├── firewood/              # Core package
│   ├── cli.py            # Command-line interface
│   ├── config.py         # Configuration management
│   ├── models.py         # Data models
│   ├── session.py        # Session management
│   ├── storage.py        # Storage backends
│   ├── logging_config.py # Logging setup
│   ├── setup_cli.py      # Setup wizard
│   ├── agent/            # Agent management
│   │   ├── executor.py   # Agent execution
│   │   └── storage.py    # Agent storage
│   ├── bridges/          # Bridge implementations
│   │   ├── base.py       # Base bridge interface
│   │   ├── manager.py    # Bridge lifecycle
│   │   ├── models.py     # Bridge data models
│   │   ├── state.py      # Bridge state management
│   │   ├── cli/          # Terminal UI bridge
│   │   ├── github/       # GitHub integration
│   │   ├── gitea/        # Gitea integration
│   │   └── feishu/       # Feishu integration
│   ├── data/             # Built-in data
│   │   ├── skills/       # Skill definitions
│   │   └── team/         # Team roles & members
│   ├── flame/            # Flame runtime integration
│   ├── providers/        # LLM provider implementations
│   │   ├── base.py       # Base provider interface
│   │   ├── agent_provider.py  # Unified provider using OpenAI Agents SDK
│   │   └── factory.py    # Provider factory
│   ├── functions/        # Built-in functions
│   │   ├── manager.py    # Function management
│   │   ├── filesystem.py # File operations
│   │   ├── http.py       # HTTP operations
│   │   ├── shell.py      # Shell/environment operations
│   │   ├── skills.py     # Skill loading
│   │   ├── team.py       # Team operations
│   │   └── tokens.py     # Token management
│   ├── skills/           # Skills management
│   │   ├── models.py     # Skill data models
│   │   ├── loader.py     # Skill loading
│   │   ├── manager.py    # Skill lifecycle
│   │   ├── discovery.py  # Skill discovery
│   │   ├── executor.py   # Skill execution
│   │   ├── validator.py  # Skill validation
│   │   └── internal.py   # Internal skill functions
│   └── team/             # Team management
│       ├── discovery.py  # Team discovery
│       ├── manager.py    # Team lifecycle
│       └── models.py     # Team data models
│   └── utils/            # Utility modules
│       ├── discovery.py  # Common discovery patterns
│       └── resources.py  # Resource utilities
├── examples/             # Usage examples
├── tests/                # Test suite
├── docs/                 # Documentation
└── skills/               # User-installed skills

🧪 Development

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=firewood --cov-report=html

# Run specific test file
pytest tests/test_function_manager.py

# Run with verbose output
pytest -v

Code Quality

# Lint and fix
ruff check --fix firewood/ tests/

# Format code
ruff format firewood/ tests/

# Type checking
mypy firewood/

Debugging

# Enable verbose logging (DEBUG level)
firewood -v

# View recent logs
firewood --show-logs --log-lines 100

# Show log file location
firewood --log-path

# List all sessions with details
firewood --list-sessions

# Validate configuration
firewood --validate-api-key

# List installed and enabled skills
firewood --list-skills

📚 Documentation

QUICKSTART.md - Get started in 5 minutes
ABOUT_FIREWOOD.md - Project philosophy and architecture
CHANGELOG.md - Version history and changes
AGENTS.md - AI coding agent guidance
docs/design/ - Technical design documentation
docs/bugs/ - Bug fix documentation
docs/testing/ - Testing documentation

Key Design Documents

Start with the Design Documentation Index for a complete overview.

Feature Documentation (consolidated, authoritative):

Providers - Multi-provider system (OpenAI, Kimi, Custom)
Function Calling - Universal function calling (filesystem, HTTP, shell)
Skills - Agent Skills system and extensibility
Streaming - Real-time response streaming
Logging - Logging system and configuration
CLI & Setup - CLI commands and setup wizard

Core Design Specs:

Agent Architecture - Core agent design with session persistence
GitHub Bridge - GitHub integration for issue automation

🎯 Use Cases

Development Assistant

You: Read my Python script and suggest improvements
Firewood: [reads file, analyzes code, provides suggestions]

You: Create a README for this project
Firewood: [analyzes project, writes comprehensive README]

Data Analysis

You: Fetch data from https://api.example.com/data
Firewood: [makes HTTP request, analyzes data]

You: Save the results to results.json
Firewood: [writes formatted JSON file]

Automation

You: Read config.yaml and make an API call with those settings
Firewood: [reads config, makes HTTP request, returns results]

Learning and Research

You: Explain how authentication works in auth.py
Firewood: [reads and analyzes code, provides detailed explanation]

Weather Queries (with Weather Skill)

You: What's the weather like in Tokyo?
Firewood: [uses weather skill to fetch real-time weather data]

You: Should I bring an umbrella in London today?
Firewood: [checks weather and provides advice]

🔒 Security

API Keys

Never logged or displayed
Stored securely in system keyring (optional)
Provider-specific environment variables
Config file with appropriate permissions

File Operations

Path validation (no directory traversal)
Configurable base path
Read-only mode option
Allowed paths whitelist

HTTP Operations

URL validation (http/https only)
Domain whitelisting support
Configurable timeouts
Safe error handling

🤝 Contributing

Contributions are welcome! Please see:

AGENTS.md for AI coding agent guidance
docs/templates/ for documentation templates

Development Workflow

Fork the repository
Create a feature branch
Make your changes
Add tests
Run test suite and linters
Submit pull request

🐛 Troubleshooting

Common Issues

API Key Not Found:

# Verify API key is set
firewood --validate-api-key

# Run setup again
firewood --setup

Functions Not Working:

# Check if functions are enabled
firewood --show-config

# Verify functions are enabled in config file
# ~/.firewood/config.toml should have:
# [functions]
# enabled = true

# Test with simple function call
# Ask: "Read the README.md file"
# or: "Get my PATH environment variable"

# Check logs for function execution
firewood --show-logs --log-lines 50

Sessions Not Saving:

# Check permissions
ls -la ~/.firewood/

# Check logs
firewood --show-logs

📊 Statistics

Test Coverage

480+ tests passing ✅
50%+ code coverage (CI enforced threshold)
Comprehensive function calling tests
Multi-provider integration tests
Skills system tests
Streaming implementation tests
Team system tests
Bridge system tests

Providers Supported

Provider	Status	Function Calling	Streaming	Models
OpenAI	✅ Ready	✅ Full	✅ Yes	gpt-4o, gpt-4o-mini, gpt-4, gpt-4-turbo, gpt-3.5-turbo, o1, o1-mini, o3, o3-mini
Anthropic	✅ Ready	✅ Full	✅ Yes	claude-3-5-sonnet, claude-3-opus, claude-3-sonnet, claude-3-haiku
Kimi/Moonshot	✅ Ready	✅ Full	✅ Yes	kimi-k2.5, moonshot-v1-8k/32k/128k
Custom	✅ Ready	✅ Full	✅ Yes	Any OpenAI-compatible API (Ollama, vLLM, etc.)

Note: All providers use a unified AgentProvider implementation powered by the OpenAI Agents SDK.

Built-in Functions

8 Filesystem functions (read_file, read_dir, write_file, append_file, delete_file, rename_fs, delete_dirs, create_dirs) — 2 always, 6 write-enabled
5 HTTP functions (http_get, http_post, http_put, http_patch, http_delete)
2 Shell functions (get_env, run_cmd)
1 Token function (list_tokens)
1 Skills function (load_skill)
2 Team functions (intro_member, assign_tasks)
19 total functions (12 always available, 6 conditional on write access, 1 token)

Skills

Weather skill - Real-time weather data via Open-Meteo API
Git skill - Git CLI operations via run_cmd
GitHub skill - GitHub operations via gh CLI
Gitea skill - Gitea operations
Makefile skill - Makefile patterns and best practices
Backend Engineering skill - Backend development practices
Communication skill - Communication templates
Project Management skill - PM practices and templates
System Design skill - System design methodology
System Test skill - Testing practices and templates
Custom skills - Create your own following Agent Skills spec

Team System

4 Roles - TPM, Dev, Architect, QA
10 Team Members - Pre-configured agent personas

🗺️ Roadmap

Current (v0.1.x) ✅

Next (v0.2.x)

Additional providers (Google Gemini)
Enhanced skills library (code review, testing, debugging)
Skills registry and marketplace
MCP (Model Context Protocol) integration
SQLite storage backend option
Session search and filtering
Cost tracking per provider

Future (v0.3.x)

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built on Flame framework
UI powered by Textual
Testing with pytest

📞 Support

Issues: GitHub Issues
Documentation: docs/
Examples: examples/

Built on Flame 🔥
Enhanced by Firewood 🪵
Made for you ❤️

Uh oh!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Firewood 🔥

✨ Features

🤖 Multi-Provider Support (Unified Agent Architecture)

🛠️ Universal Function Calling

💾 Session Persistence

🎭 Skills System

👥 Team System

🌉 Bridge System

🎨 Beautiful Terminal UI

🔧 Flexible Configuration

🚀 Quick Start

Installation

Setup

Start Chatting

📖 Usage

Basic Commands

Team Commands

Bridge Commands

Keyboard Shortcuts (In Chat)

Function Calling Examples

Filesystem Functions

HTTP Functions

Shell Functions

Skills

Configuration

Config File Location

Example Configuration

Environment Variables

🔧 Function Calling

Built-in Functions

Filesystem Functions

HTTP Functions

Shell Functions

Token Functions

Skills Functions

Team Functions

How It Works

📁 Project Structure

🧪 Development

Running Tests

Code Quality

Debugging

📚 Documentation

Key Design Documents

🎯 Use Cases

Development Assistant

Data Analysis

Automation

Learning and Research

Weather Queries (with Weather Skill)

🔒 Security

API Keys

File Operations

HTTP Operations

🤝 Contributing

Development Workflow

🐛 Troubleshooting

Common Issues

📊 Statistics

Test Coverage

Providers Supported

Built-in Functions

Skills

Team System

🗺️ Roadmap

Current (v0.1.x) ✅

Next (v0.2.x)

Future (v0.3.x)

📜 License

🙏 Acknowledgments

📞 Support