FrankHui/paragents provides a TUI-first framework for running parallel AI agent sessions, enhancing productivity and safety. It addresses the need for managing multiple concurrent agent tasks by offering conflict-safe execution, persistent context across turns, and explicit permission/approval gates for risky actions, benefiting power users and researchers managing complex AI workflows.

How It Works

The core architecture utilizes a session-based scheduler and worker model, reusing a single agent instance per session for continuity. It features per-session context and memory persistence, coupled with preflight conflict checks, particularly for output collisions. An explicit approval flow requires user consent before potentially hazardous operations, ensuring a controlled execution environment. The TUI-first design facilitates simultaneous observation of multiple agent sessions.

Quick Start & Requirements

• Installation: Run uv sync to install dependencies.
• Execution: Start the TUI with uv run python main.py.
• Prerequisites: Requires Python >= 3.11, uv installed, and an OpenAI-compatible endpoint configured in runtime_config.json.
• Setup: An interactive setup guides first-time users if runtime_config.json is absent; reconfiguration is available via the /setup command within the TUI.

Highlighted Details

• Permission Governance: Implements PermissionsConfig.capabilities and fs_scopes for granular control over agent actions, drawing inspiration from established agent frameworks.
• Context Management: Features session continuity, prompt assembly abstraction, and robust interruption/recovery mechanisms via checkpointing and state storage.
• Conflict Safety: Includes preflight checks for output conflicts and an approval workflow (needs_approval, blocked, auto_approved) for user-sanctioned actions.

Maintenance & Community

A TODO roadmap is detailed in a separate TODO.md file. Contributions are encouraged via small, reviewable Pull Requests. No specific community channels or sponsorship details are provided in the README.

Licensing & Compatibility

Declared as MIT license, permitting commercial use and integration with closed-source projects. Users are advised to add a top-level LICENSE file before public distribution.

Limitations & Caveats

This project is explicitly marked as "Not production-ready" and offers "No stability guarantees on internal APIs." Behavior may prioritize experimentation over backward compatibility, and internal APIs are subject to change.