paragents

Parallel agent sessions in one panel, with permission-aware tools, preflight conflict checks.

Remembers context across turns. Asks before risky actions. Runs parallel sessions with conflict-safe execution.
TUI-first workflow, extensible tools, and explicit policy gates.

Inspired by 4 other agent repos: claude-code, mercury-agent, hermes-agent, nanobot.

English | 简体中文

Demo

Quick Start (TUI Only)

1. Install dependencies

uv sync

1. Start TUI

uv run python main.py

1. First run setup

• If runtime_config.json is missing, startup enters interactive setup.
• You can reconfigure in TUI with:
  • /setup
  • /show-config

1. Command reference

Why Parallel-Agent

The current design focuses on multi-session parallelism with per-session continuity:

• Session-based scheduler and worker model
• Single active agent instance per session (reused across turns)
• Session-level context + memory persistence
• Preflight conflict checks (especially output conflicts) and approval flow
• TUI-first operations for observing multiple sessions

flowchart LR
  UserInput[UserInput] --> Scheduler[Scheduler]
  Scheduler --> SessionQueue[SessionPromptQueue]
  SessionQueue --> SessionWorker[SessionWorker]
  SessionWorker --> AgentInstance[AgentInstance]
  AgentInstance --> Tools[ToolsAndPermissions]
  AgentInstance --> ContextState[SessionRuntimeState]
  ContextState --> Scheduler

Key implementation files:

• main.py
• scheduler.py
• agent_instance.py
• session_runtime.py
• tui_app.py

Cross-Repo Learning Notes (inlined)

Legend:

• Code verified: implementation or interface is directly confirmed in code.
• Docs/changelog signal: mainly inferred from README/changelog/config examples; full core implementation may not be fully open.

1) Permission and Capability Governance

2) Context, Compaction, and Recovery

3) Current Paragents Conclusions

• The "policy config + ask/deny semantics" model is partially in place with permissions.json + blocked/needs_approval/auto_approved.
• Compared with claude-code, current gaps are mainly:
  • ask/deny logic is still fragmented across capability/policy domains instead of one unified rule layer;
  • missing a stronger hierarchical policy model (managed/user/project) and tool-level unified rule interpretation.

Requirements

From pyproject.toml:

• Python >=3.11
• Runtime dependencies:
  • httpx
  • prompt-toolkit
• Dev dependency group:
  • pytest

System/runtime prerequisites:

• uv installed
• An OpenAI-compatible endpoint configured in runtime_config.json (interactive setup on first run)

TODO Roadmap

The detailed roadmap is in a dedicated file for readability:

• TODO.md

At a glance:

• P0: IM integration, multi-session usability, and recovery hardening
• P1: context quality, policy unification, conflict UX, session invariants
• P2: observability, regression suites, and UI state-machine consistency

Non-Goals / Caveats

• Not production-ready
• No stability guarantees on internal APIs
• Behavior may prioritize experimentation over strict backward compatibility

Testing

Run core TUI regressions:

uv run pytest -q tests/test_tui_layout.py tests/test_tui_commands.py tests/test_run_approval_flow.py

License

MIT.

Note: this README declares MIT intent. If a top-level LICENSE file is missing, add one before public distribution.

Contributing

Small, focused PRs are preferred.

• Keep changes easy to review and easy to hack on.
• Add or update tests for behavioral changes.
• Prefer readability over cleverness.