falcon

Falcon

Falcon is a terminal-based AI agent for API developers. It combines API testing, debugging, and code analysis in an interactive TUI powered by a ReAct (Reason+Act) loop. Built in Go with the Charm ecosystem (Bubble Tea, Lip Gloss, Glamour).

Features

• ReAct Agent Loop — Think, act, observe. Falcon reasons through your request and executes tools autonomously until it has a final answer.
• 28+ Specialized Tools — HTTP requests, JSON Schema validation, test generation, security scanning, performance testing, code analysis, and more.
• Multiple LLM Backends — Ollama (local or cloud), Google Gemini, and OpenRouter (gateway to 100+ models).
• Interactive TUI — Real-time streaming output, keyboard shortcuts, model/environment switching, confirmation prompts for file writes.
• Persistent Memory — The agent recalls project knowledge across sessions.
• CLI Mode — Execute saved requests non-interactively for CI pipelines.

Table of Contents

• Quick Start
• Installation
• Configuration
• Usage
• Tools Reference
• LLM Providers
• Architecture
• Development

Quick Start

# Build
go build -o falcon ./cmd/falcon

# First run — launches the setup wizard
./falcon

# Start testing
./falcon --framework gin

On first run, Falcon creates a .falcon/ folder in the current directory and walks you through LLM provider setup.

Installation

Build from Source

Prerequisites: Go 1.21+

git clone https://github.com/blackcoderx/falcon
cd falcon
go build -o falcon ./cmd/falcon          # Unix/macOS
go build -o falcon.exe ./cmd/falcon      # Windows

Self-Update

falcon update

Falcon fetches the latest release from GitHub and replaces the binary in-place.

Multi-Platform Release

goreleaser release

Configuration

Falcon uses two config files:

Run the setup wizard at any time:

falcon config

Example Global Config

default_provider: gemini
theme: dark

providers:
  ollama:
    model: llama3
    config:
      mode: local
      url: http://localhost:11434

  gemini:
    model: gemini-2.5-flash-lite
    config:
      api_key: YOUR_API_KEY

  openrouter:
    model: google/gemini-2.5-flash-lite
    config:
      api_key: sk-or-...

Environment Variables

Usage

Interactive Mode (Default)

./falcon                        # Start the TUI
./falcon --framework gin        # Specify your API framework
./falcon --no-index             # Skip automatic spec indexing

CLI Mode (Non-interactive)

Execute a saved request and exit — useful for CI:

./falcon --request get-users --env prod
./falcon -r create-user -e staging

Subcommands

falcon version    # Print version, commit, build date
falcon config     # Run the setup wizard
falcon update     # Self-update to latest release

Keyboard Shortcuts

Example Prompts

test all endpoints with invalid auth tokens
run a load test against /api/users with 50 concurrent users
find the handler for POST /orders and check for SQL injection
generate functional tests for the spec at openapi.yaml
save a request called get-profile that hits GET /me with bearer auth
compare today's response to the baseline snapshot

Tools Reference

Falcon's agent has access to 28+ tools organized by domain.

HTTP & Assertions

Persistence & Variables

Debugging & Code Analysis

Testing

Spec & Automation

LLM Providers

Falcon supports pluggable LLM backends. Switch between them at any time with /model inside the TUI.

Supported Providers

Adding a New Provider

1. Create pkg/llm/myprovider/myprovider.go — implement LLMClient:

   type LLMClient interface {
       Chat(messages []Message) (string, error)
       ChatStream(messages []Message, callback StreamCallback) (string, error)
       CheckConnection() error
       GetModel() string
   }
   

2. Create pkg/llm/myprovider/myprovider_provider.go — implement Provider and register via init().
3. Add a blank import to pkg/llm/register_providers.go.

No changes to core code required — the provider appears automatically in the setup wizard.

.falcon/ Folder Structure

Falcon stores all artifacts in a flat, type-prefixed layout:

.falcon/                        # Per-project
├── config.yaml                 # Project config
├── falcon.md                   # API knowledge base (written by agent)
├── spec.yaml                   # Ingested API spec
├── manifest.json               # Endpoint graph
├── variables.json              # Global variables
├── environments/
│   ├── dev.yaml
│   └── prod.yaml
├── requests/
│   ├── get-users.yaml
│   └── create-user.yaml
├── sessions/
│   └── session_<timestamp>.json
├── baselines/
│   └── baseline_users_api.json
├── flows/
│   ├── unit_get_users.yaml
│   └── integration_login_create_delete.yaml
└── reports/
    ├── performance_report_users_api_20260227.md
    └── security_report_auth_api_20260227.md

~/.falcon/                      # Global (across all projects)
├── config.yaml
└── memory.json

Naming conventions:

• Reports: <type>_report_<api-name>_<timestamp>.md
• Flows: <type>_<description>.yaml

Architecture

cmd/falcon/
└── main.go              ← Cobra CLI, .env loading, TUI launch

pkg/core/
├── agent.go             ← Agent struct, tool registry, mutex-guarded state
├── react.go             ← ReAct loop (think → act → observe, 3× retry)
├── types.go             ← Tool & AgentEvent interfaces
├── memory.go            ← Persistent memory store
├── analysis.go          ← Stack trace parsing
├── prompt/              ← Modular system prompt builder
└── tools/               ← 28+ tools by domain

pkg/llm/
├── client.go            ← LLMClient interface
├── registry.go          ← Self-registering provider registry
├── ollama/              ← Ollama provider
├── gemini/              ← Google Gemini provider
└── openrouter/          ← OpenRouter provider

pkg/tui/
├── app.go               ← Entry point
├── model.go             ← UI state
├── update.go            ← Event handling (Elm architecture)
├── view.go              ← Layout rendering
└── styles.go            ← Lip Gloss styling

pkg/storage/             ← YAML/env file I/O, variable substitution

ReAct Loop

User input
   ↓
Build system prompt (tool descriptions + memory)
   ↓
LLM streaming call (retry up to 3× with backoff)
   ↓
Parse response
   ├── ACTION: tool_name({...})  →  Execute tool  →  Append observation  →  Loop
   └── Final Answer: ...         →  Return to user

Tool Interface

type Tool interface {
    Name() string           // snake_case identifier
    Description() string    // Included in system prompt
    Parameters() string     // JSON Schema
    Execute(args string) (string, error)
}

Agent Events (streamed to TUI in real-time)

Development

Commands

# Build
go build -o falcon ./cmd/falcon

# Test
go test ./...                             # All tests
go test ./pkg/core/...                    # Core package
go test -v -run TestName ./pkg/core/...   # Single test
go test -cover ./...                      # With coverage

# Format
go fmt ./...

Adding a New Tool

1. Create pkg/core/tools/<module>/tool.go and implement the Tool interface.
2. Register it in pkg/core/tools/registry.go within the appropriate register*() function.
3. Update the system prompt reference in pkg/core/prompt/tools.go.

If the tool writes reports, call shared.ValidateReportContent() before returning.

If the tool writes files, implement ConfirmableTool to hook into the TUI confirmation workflow.

Dependencies

License

See LICENSE.