Flora

Act to get things done—and to find things out.

Flora is a terminal-first general-purpose agent for web research, document and spreadsheet processing, external tool integration, and delivering files and reports. Its pixel-art character, floral logo, and purple/mint palette follow the project's visual identity.

Run flora in any working directory, enter your Base URL, API Key, and Model, and get started. The current directory becomes the workspace, and a session ID is generated automatically. API keys are entered without being displayed and are used only within the current process.

By default, the main agent and subagents in new general-purpose sessions have no cumulative limits on model calls, tool calls, input/output tokens, or session duration. Usage is still tracked, and startup displays Budget: unlimited. Per-response output limits, request timeouts, bounded retries, and concurrency safeguards remain in effect. Set explicit budget limits through a profile when needed.

Python 3.11+ · Linux / macOS / Windows WSL · Apache-2.0

After installing pipx:

git clone --branch general-agent https://github.com/wongzbb/Flora.git
cd Flora
pipx install '.[general,mcp]'
pipx ensurepath

Open a new terminal after updating PATH for the first time. Start Flora in the project or folder you want to work with:

flora

Enter values as prompted, without surrounding quotes. API keys are not echoed or written to configuration files, conversations, or environment variables. If the service supports /models, Flora lists the returned models; enter a number or the full model ID. If model listing is unavailable, enter the model ID manually.

The terminal application does not require a browser. For browser automation, install .[general,mcp,browser] and Playwright Chromium for your environment. See the manual for details.

flora                          # Use the current directory and create a session automatically
flora -C /path/to/project       # Specify a working directory
flora --resume                 # Choose a previous session in the current directory
flora --resume SESSION_ID      # Open a specific session directly
flora --config /path/profile.json

Flora prompts for model connection details on every launch, including when resuming a session. Resumed sessions retain their original endpoint, model, tools, and budgets; the API key can be updated. Continue chatting after opening a saved session, or explicitly continue an unfinished task with /resume. Start a new session when changing the model or capability configuration. Saved sessions retain the budget settings they were created with. If a resumed session shows finite limits, /new uses the current defaults without erasing the previous session's usage records.

Enter a task in the conversation. Press Enter to send, Alt+Enter for a new line, and Tab to complete commands:

During execution, Ctrl+C requests a pause at the next execution boundary; an in-flight request must first return or time out. Press Ctrl+D at the prompt to exit. See the terminal manual for detailed commands and recovery rules.

The terminal displays actual model responses and tool interactions, identifying the main agent and subagents. When the model supports streaming, content appears as it arrives. Programs execute only after strict validation. View full request prompts with /log 0; /log shows the most recent records by default.

The general-purpose entry point requests JSON output by default and uses bounded recovery with explicit usage accounting for transient connection errors, rate limits, and selected server errors. Authentication failures and incorrect model endpoints produce specific explanations. Incomplete programs from interrupted streams are not executed, and tool calls with unknown outcomes are not automatically repeated. See troubleshooting.

New general-purpose sessions use block-list-v2 with explicit success/error consumers for observe, then lower the source to the original IR for validation and execution. The candidate, diagnostic, and contract mechanisms remain unchanged. Read-only workspace observations, no-progress stream cutoffs, and a deadline shared across the compilation round are included. If the output budget is exhausted without producing a program body, Flora no longer repeats the same format-repair attempt. Existing sessions do not automatically switch protocols or tool fingerprints.

After a consumer fault, the compiler supplies a bounded index of existing real receipts so the model can repair the remaining computation rather than redo the entire task. This is evidence-based recovery guidance, not a deterministic correctness guarantee. These changes do not bypass network protections or guarantee that upstream models and networks are always available.

Subagents handle reading, research, and analysis by default; the main agent centrally performs file writes and external modifications. Every subagent runs the Flora kernel and is distinct from the kernel's internal candidate programs. By default, each session can create up to 8 subagents, with separately tracked budgets. See the manual for exact limits and permissions.

Model proposals are compiled into inspectable programs. Actions can both advance the task and help distinguish between competing proposals. Actual tool results and consumer checks are used to synthesize local contracts that guide what happens next. Independent subagents use the same mechanism, preserving their own trajectories and unknown outcomes.

Tool permissions and path checks are not an operating-system sandbox. Command execution is available to the main agent only when --allow-commands is explicitly enabled. MCP and browser capabilities are enabled through configuration. OCR for scanned documents, audio/video understanding, and model vision input can be integrated through additional services.

• Quick start · Terminal manual
• Full manual and Python API; download manual.html for offline reading.
• Terminal validation records · General capability validation records
• Kernel baseline · Coding Agent · Project overview

src/flora/terminal/ implements the terminal interface; general/ combines application tools and subtasks; agent/, engine/, language/, checks/, and state/ implement the execution kernel; integrations/ connects models and tools. The full documentation is maintained separately on the docs branch.

New General sessions default to general-v3, block-list-v2, and compact-v1: the model generates more concise source programs, and nested pure expressions are mechanically lowered into fresh SSA operations before passing through the original IR validation, scheduling, and contract checks. The frontend does not evaluate expressions implicitly, generate additional tool calls, or switch to per-tool replanning. Existing v1/v2 sessions retain their original protocols and tool identities.

Endpoints that support DeepSeek reasoning parameters can explicitly use the low-latency profile:

# Run from this repository, or replace the profile path with its absolute path
flora --config configs/deepseek-fast.json

When prompted, enter your own Base URL, API Key via hidden input, and a model ID supported by your endpoint. The profile's deepseek-v4-flash ID is a name advertised by the test gateway, not independent verification of its underlying model weights. When using another endpoint, confirm that it supports the model ID and reasoning parameters. The profile contains no API key or fixed gateway address. It enables low-effort reasoning rather than disabling reasoning. Start a new session; do not impose this profile on an existing session. Running flora alone does not automatically load this performance profile.

The v3 file tools explicitly distinguish create_file, update_file, and append_lines. Updates and appends still require the full observed hash, and writes still produce real receipts. They do not silently overwrite files, bypass path restrictions, or replay effects with unknown outcomes. Compilation has a shared deadline. Optional stalled-stream recovery discards only unexecuted partial programs; it does not replay tools that have already executed.

Limitations: Models and upstream services can still produce errors and long-tail response times. In some proxy DNS environments, existing network policies may still block web research. This version does not guarantee success on arbitrary tasks. A normal completion status or an honest report of a network failure does not mean that the research task succeeded.

From the repository root, use a Python environment with the project dependencies installed:

python -m unittest discover -s tests -q

The default tests do not call real model APIs. tests/live_*_probe.py scripts are reusable, manually invoked validation tools for general tasks, the installed terminal entry point, and consumer-fault recovery. Use --help to inspect their arguments. Explicitly specify the endpoint and output directory; API keys are provided through hidden input. Keep run outputs outside the repository, and do not commit logs or credentials.