paragents

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

| Dimension | Paragents | claude-code | mercury-agent | hermes-agent | nanobot | |---|---|---|---|---|---| | Capability switches | PermissionsConfig.capabilities (Code verified) | Tool-level permission governance in settings (Docs/changelog signal) | permissions.yaml + capability registry (Code verified) | Governance via toolset/gateway composition (Code verified) | ToolsConfig level toggles (Code verified) | | ask/deny semantics | needs_approval / blocked / auto_approved (Code verified) | Explicit ask/deny (Code verified) | Command pattern-based approvals (Code verified) | Approval is more runtime-pipeline oriented (Code verified) | Primarily enable/sandbox/restrict style (Code verified) | | File scope control | fs_scopes (Code verified) | Combined through tool permissions + policy layering (Docs/changelog signal) | File scopes (Code verified) | Mostly enforced in tool runtime (Code verified) | restrict_to_workspace (Code verified) | | Sandbox/network policy | Relatively lightweight currently (Code verified) | sandbox.network.* (Code verified) | Basic shell constraints (e.g., cwd) (Code verified) | More gateway/runtime governance oriented (Code verified) | exec.sandbox + SSRF allowlist (Code verified) |

2) Context, Compaction, and Recovery

| Dimension | Paragents | claude-code | mercury-agent | hermes-agent | nanobot | |---|---|---|---|---|---| | Session continuity | Session worker + one reused agent per session (Code verified) | Strong --resume/--continue semantics (Docs/changelog signal) | conversationId-scoped short-term memory (Code verified) | Session + contextvars isolation (Code verified) | SessionManager persistence (Code verified) | | Prompt construction | PromptAssembler abstraction (Code verified) | Core internals not fully public (Docs/changelog signal) | system + relevantFacts + recentMemory + user (Code verified) | Unified through ContextEngine (Code verified) | Layered assembly via ContextBuilder (Code verified) | | Compaction strategy | should_compact()/compact() (Code verified) | auto-compact + pre-compact hook (Docs/changelog signal) | Mainly recent-N control (Code verified) | ContextEngine + Compressor (Code verified) | online consolidate + idle auto-compact (Code verified) | | Interruption/recovery | CheckpointRecovery + SessionStateStore (Code verified) | Ongoing long-session recovery hardening (Docs/changelog signal) | Persistent memory resume (Code verified) | checkpoint manager (Code verified) | runtime checkpoint + keep-context on stop (Code verified) |

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.