paragents - GitLite

KO | EN

gitlite — search

#javascript #react #typescript #llm #android #machine-learning #rust #deep-learning #docker #java #windows #awesome-list #vue #ios

paragents

(★ 241)

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

파일 탐색기

최종 버전 다운로드 (.zip)

- logo.png
- paragent_demo.gif
- prompt_keynode_refresh.txt
- py_fail_after_sleep.py
- py_long_logs_for_paging.py
- py_prompt_input.py
- py_sleep_success.py
- README.md
- sh_fail_after_sleep.sh
- sh_prompt_input.sh
- sh_sleep_success.sh
- conftest.py
- test_approval_pause_flow.py
- test_approval_view.py
- test_cli_approvals.py
- test_cli_ui.py
- test_context_memory_pipeline.py
- test_hook_runtime.py
- test_p1_p3_capabilities.py
- test_permissions_and_tools.py
- test_preflight_intent.py
- test_run_approval_flow.py
- test_scheduler_debug_prompt_ids.py
- test_scheduler_output_conflicts.py
- test_scheduler_serialize_override.py
- test_session_context_continuity.py
- test_session_runtime.py
- test_task_id_resolution.py
- test_tui_commands.py
- test_tui_layout.py
- test_tui_state_mapping.py
.gitignore
.python-version
agent_instance.py
approval_view.py
CHANGELOG.md
cli_approvals.py
config.py
dev_plan.md
hook_runtime.py
id_refs.py
llm_client.py
main.py
mcp_runtime.py
memory.py
permissions.py
preflight_intent.py
pyproject.toml
README.md
README.zh-CN.md
scheduler.py
session_runtime.py
task.py
TODO.md
tools.py
tui_app.py
tui_state.py
ui_cli.py
uv.lock
VERSION

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<p align="center">
  <img src="assets/logo.png" alt="Paragents Logo"/>
</p>

<p align="center"><strong>
Parallel agent sessions in one panel, with permission-aware tools, preflight conflict checks.
</strong></p>

<p align="center">
Remembers context across turns. Asks before risky actions. Runs parallel sessions with conflict-safe execution.
<br />
TUI-first workflow, extensible tools, and explicit policy gates.
</p>

<p align="center">
  Inspired by 4 other agent repos:
  <a href="https://github.com/anthropics/claude-code">claude-code</a>,
  <a href="https://github.com/cosmicstack-labs/mercury-agent">mercury-agent</a>,
  <a href="https://github.com/NousResearch/hermes-agent">hermes-agent</a>,
  <a href="https://github.com/HKUDS/nanobot">nanobot</a>.
</p>

<p align="center">
  <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+" />
  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License" />
</p>

<p align="center">
  <a href="./README.md">English</a> | <a href="./README.zh-CN.md">简体中文</a>
</p>

## Demo

![Paragents demo](https://raw.githubusercontent.com/FrankHui/paragents/main/assets/paragent_demo.gif)

## Quick Start (TUI Only)

1. Install dependencies

```bash
uv sync
```

2. Start TUI

```bash
uv run python main.py
```

3. First run setup

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

4. Command reference

| Command | Purpose |
|---|---|
| `/new <text>` | Create a new foreground session with the initial prompt |
| `/prompt <text>` | Continue current foreground session with a new prompt |
| `/submit <text>` | Submit a new background session |
| `/list` | List current sessions and their status |
| `/switch <session_ref>` | Switch foreground focus to a target session |
| `/close <session_ref>` | Close a session and release its slot |
| `/approvals` | Show pending approval requests |
| `/approve <request_ref> [always]` | Approve a pending request (optional persistent allow) |
| `/deny <request_ref>` | Deny a pending request |
| `/pause <prompt_ref>` | Pause a running prompt |
| `/resume <session_ref>` | Resume paused prompt in target session |
| `/cancel <prompt_ref>` | Cancel target prompt |
| `/permissions` | Print current effective permission config |
| `/setup` | Re-run runtime/provider setup |
| `/show-config` | Show runtime config file path and provider info |
| `/quit` | Exit TUI |

## 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

```mermaid
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`](https://docs.astral.sh/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](./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:

```bash
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.