Metadata-Version: 2.4
Name: thegent
Version: 0.1.0
Summary: Unified agent orchestration CLI for Factory skills, droids, and multi-agent workflows
Project-URL: Homepage, https://github.com/kooshapari/thegent
Project-URL: Repository, https://github.com/kooshapari/thegent
Project-URL: Documentation, https://github.com/kooshapari/thegent#readme
Author-email: Koosha Paridehpour <kooshapari@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agent,ai,automation,claude,cli,codex,droid,factory,mcp,orchestration
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: apscheduler>=3.10.4
Requires-Dist: arxiv>=2.1.3
Requires-Dist: cachetools>=5.5.2
Requires-Dist: duckduckgo-search>=7.3.2
Requires-Dist: extism>=1.0.2; platform_system == 'Darwin' and platform_machine == 'arm64'
Requires-Dist: fastjsonschema>=2.21.1
Requires-Dist: fastmcp[tasks]>=3.0.0
Requires-Dist: feedparser>=6.0.11
Requires-Dist: granian>=1.7.4
Requires-Dist: httpx>=0.28.1
Requires-Dist: opentelemetry-api>=1.31.0
Requires-Dist: opentelemetry-sdk>=1.31.0
Requires-Dist: orjson; implementation_name == 'cpython'
Requires-Dist: persistdict>=0.2.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: playwright>=1.50.0
Requires-Dist: praw>=7.8.1
Requires-Dist: psutil>=7.0.0
Requires-Dist: pybreaker>=1.2.0
Requires-Dist: pydantic-settings>=2.8.1
Requires-Dist: pydantic>=2.12.5
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: rich>=13.9.4
Requires-Dist: rtoml>=0.12.0
Requires-Dist: ruamel-yaml>=0.18.6
Requires-Dist: scholarly>=1.7.11
Requires-Dist: starlette>=0.46.0
Requires-Dist: structlog>=24.0.0
Requires-Dist: tenacity>=9.0.0
Requires-Dist: textual>=1.0.0
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: tomli>=2.2.1
Requires-Dist: tomlkit>=0.13.2
Requires-Dist: typer>=0.16.0
Requires-Dist: ujson; implementation_name == 'pypy'
Requires-Dist: uvicorn>=0.34.0
Requires-Dist: watchdog>=6.0.0
Requires-Dist: watchfiles>=1.0.4
Provides-Extra: dev
Requires-Dist: basedpyright>=1.31.1; extra == 'dev'
Requires-Dist: mypy>=1.19.1; extra == 'dev'
Requires-Dist: pre-commit>=4.1.0; extra == 'dev'
Requires-Dist: psleak>=0.1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
Requires-Dist: pytest-benchmark>=4.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
Requires-Dist: pytest-rerunfailures>=14.0.0; extra == 'dev'
Requires-Dist: pytest-testmon<3.0.0,>=2.1.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.6.1; extra == 'dev'
Requires-Dist: pytest>=9.0.2; extra == 'dev'
Requires-Dist: radon>=6.0; extra == 'dev'
Requires-Dist: ruff>=0.15.1; extra == 'dev'
Requires-Dist: tach>=0.26.0; extra == 'dev'
Requires-Dist: ty>=0.0.2; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.12.20250915; extra == 'dev'
Requires-Dist: vulture>=2.14; extra == 'dev'
Provides-Extra: fast
Requires-Dist: curl-cffi>=0.6.0; extra == 'fast'
Description-Content-Type: text/markdown

# thegent

[![PyPI version](https://badge.fury.io/py/thegent.svg)](https://badge.fury.io/py/thegent)
[![Rust](https://img.shields.io/badge/built%20with-Rust-orange.svg)](https://www.rust-lang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

**CLI and framework for agent orchestration, governance, and lifecycle management.**

`thegent` is a CLI and framework for managing AI agent workflows, droids, and multi-agent swarms. It follows a library-first design and uses Rust extensions for performance-sensitive paths.

---

## 📋 Table of Contents

- [Key Features](#-key-features)
- [Quick Start](#-quick-start)
- [Installation](#-installation)
- [Usage](#-usage)
- [Performance at Scale](#-performance-at-scale)
- [Governance & Policy](#-governance--policy)
- [Security & Hardening](#-security--hardening)
- [Documentation](#-documentation)
- [Docs Deploy](#-docs-deploy)
- [Contributing](#-contributing)
- [License](#-license)

---

## ✨ Key Features

- ⚡ **Performance**: Rust-backed tool detection and PATH resolution (<1ms) with 10-100x speedup over shell baselines.
- 🔒 **Agent Governance**: Built-in policy enforcement, cost caps, and automated quality gates.
- 🌍 **Multi-Provider Routing**: Routing across Claude, Gemini, OpenAI, and custom local proxies.
- 🛠️ **Unified Work Stream**: Single source of truth for task management across multiple agents and projects.
- 📦 **MCP Native**: Full support for Model Context Protocol (MCP) servers and resources.
- 🔄 **Continuous Autonomy**: Background execution and session management via `thegent plan loop`.
- 🔍 **Deep Research Protocol**: Multi-source investigation workflows (Reddit, Google, GitHub).

---

## 🚀 Quick Start

### 1. Install (One Command)

**macOS / Linux:**
```bash
curl -fsSL https://raw.githubusercontent.com/kooshapari/thegent/main/scripts/bootstrap.sh | sh -s -- install
```

**Windows (PowerShell):**
```powershell
irm https://raw.githubusercontent.com/kooshapari/thegent/main/scripts/install.ps1 | iex
```

### 2. Configure & Verify
```bash
thegent install -t all --scope both --full   # Bootstrap user/system assets + provider setup
thegent doctor   # Verify environment health
```

Project onboarding commands:

```bash
thegent scaffold greenfield ./new-project --profile cli_tool
thegent scaffold brownfield ./existing-project
thegent scaffold ag-dd ./existing-project
thegent scaffold none ./existing-project
```

### 3. Run Your First Agent
```bash
thegent run "Analyze the current directory structure" free
```

---

## 📦 Installation

### Prerequisites
- Python 3.12+
- Rust (required for building performance-sensitive extensions)
- Homebrew (recommended for system dependencies)

### For Developers (From Source)
```bash
git clone https://github.com/kooshapari/thegent
cd thegent
pip install -e .
thegent install -t all --scope both --setup
thegent install-shims
thegent setup --hooks
```

### Worktree Governance (Primary-main Flow)

thegent bootstrap and shell/dotfile management support a worktree-first governance model:

- Keep your primary checkout on `main`.
- Do branch development in dedicated worktrees.
- Merge/cherry-pick branch worktree commits back into `main`.

When bootstrap runs inside a git repository, it can write a marker file:

- `.thegent-primary-main` (policy marker)

Interactive shells get a helper function through managed zsh config:

```bash
thg_new_worktree <branch> [start-point] [worktree-path]
```

This helper refuses to branch from a dirty/non-main primary checkout.

### Toolchain Setup

`thegent` uses explicit setup/install surface controls (for runtime assets, shims, hooks, and profiles).  
`--system-deps`, `--verify-mise`, and `--uninstall-mise-hooks` are legacy references and are not
part of the current parser surface.

For mise/toolchain setup, use one of:

```bash
# Use the project-standard bootstrap/install flow first.
thegent install -t all --scope both --setup

# Then manage mise with your preferred shell/toolchain installer separately.
brew install mise
echo 'eval "$(mise activate zsh)"' >> ~/.zshenv
```

---

## 🛠️ Usage

| Command | Description |
|---------|-------------|
| `thegent run <prompt>` | Execute a task in the foreground with a specific agent/model. |
| `thegent run <prompt> --skill <name>` | Execute with selected skill instructions (repeat `--skill` to stack). |
| `thegent bg <prompt>` | Start a background agent session. |
| `thegent ps` | List active and historical agent sessions. |
| `thegent skill list` | List discovered skills available for `--skill` selection. |
| `thegent skill select <name>` | Validate a skill and print exact `--skill` usage for run flows. |
| `thegent plan loop` | Continuously process work items from the unified work stream. |
| `thegent plan do-next` | Find the next actionable items from project plans and specs. |
| `thegent doctor` | Verify environment health and fix performance bottlenecks. |
| `thegent sync autopilot` | Automatic bi-directional sync: `WORK_STREAM.md` <-> GitHub Projects <-> Linear. |

Harness wrappers (`dex`, `clode`, `roid`, `droid`) route through `thegent-shims`.
Use `--native` to bypass wrapper-injected defaults/proxy routing and call the underlying native CLI directly.

Skill UX examples:

```bash
thegent skill list
thegent skill select thegent-skills
thegent run agent "run with selected skill" --skill thegent-skills
```

Unknown skill handling is explicit and non-silent:

```bash
thegent skill select missing-skill
# Skill not found: missing-skill
```

### Workstream Autosync (GitHub Projects + Linear)

Enable fully automatic reflections so agents can stay unaware of board plumbing:

```text
THGENT_WORKSTREAM_AUTOSYNC_ENABLED=1
THGENT_WORKSTREAM_AUTOSYNC_INTERVAL_SEC=60

THGENT_GH_PROJECT_SYNC_ENABLED=1
THGENT_GH_PROJECT_OWNER=<org-or-user>
THGENT_GH_PROJECT_NUMBER=<project-number>

THGENT_LINEAR_SYNC_ENABLED=1
THGENT_LINEAR_API_KEY=<linear-api-key>
THGENT_LINEAR_TEAM_ID=<linear-team-id>
```

Run once:

```text
thegent sync autopilot --once
```

Run continuously:

```text
thegent sync autopilot --interval 60
```

Task entrypoints:

```text
task sync:autopilot
task sync:autopilot:once
```

---

## 📊 Performance at Scale

| Operation | Legacy (Shell) | thegent (Rust) | Improvement |
|-----------|----------------|----------------|-------------|
| Tool Detection | 60ms | **1ms** | **60x** |
| PATH Resolution | 20ms | **0.5ms** | **40x** |
| Process Scanning | 50ms | **0.5ms** | **100x** |
| Hook Execution | 200ms | **20ms** | **10x** |

---

## 🛡 Governance & Policy

`thegent` treats AI agency as a governed resource:
1. **Cost Control**: Define per-session and per-project token/dollar budgets.
2. **Quality Gates**: Automatic validation of agent outputs against defined specifications.
3. **Policy Enforcement**: Centralized `governance/` module for enforcing security and ethical constraints.
4. **Audit Logs**: Full traceability of agent actions, including tool use and thought processes.

---

## 🔐 Security & Hardening

**Security controls for agentic operations:**
- **Minimal Surface**: Core logic isolated in Rust for performance and security.
- **Stealth Scrapers**: Built-in mechanisms to bypass scraping blocks and protect agent anonymity.
- **Path Isolation**: Strict control over the execution environment via optimized shims.
- **Secret Management**: Secure storage for API keys and provider credentials.

---

## 📚 Documentation

- **[Public Docsite](./docs/site/)** — VitePress-powered public documentation. Run locally with `bun run dev` from `docs/site/`. See [docs/site/README.md](./docs/site/README.md) for full setup instructions.
- **[Docsets](./docs/docsets/)** — Audience-based documentation tracks.
  - [Developer (Internal)](./docs/docsets/developer/internal/)
  - [Developer (External)](./docs/docsets/developer/external/)
  - [Technical User](./docs/docsets/user/)
  - [Agent Operator](./docs/docsets/agent/)
- **[CLIProxyAPI Issue Board](./docs/docset/CLIProxyAPI_ISSUE_BOARD.md)** — 961 tracked GitHub issues from CLIProxyAPI/Plus with thegent solutions.
- **[Quick Start Guide](./docs/guides/QUICK_START.md)** — Get up and running in 5 minutes.
- **[Complete User Guide](./docs/guides/COMPLETE_USER_GUIDE.md)** — Deep dive into features.
- **[Installation Guide](./docs/guides/INSTALLATION.md)** — Advanced setup options.
<<<<<<< HEAD
- **[Provider Setup Guide](./docs/guides/PROVIDER_SETUP_GUIDE.md)** — cliproxy login, provider/model routing, adapter vs native behavior, and troubleshooting.
- **[Changelog](./CHANGELOG.md)** — Keep-a-Changelog release history with active `Unreleased` section.
- **[Changelog Process](./docs/guides/CHANGELOG_PROCESS.md)** — How to add, classify, and release changelog entries.
- **[Changelog Entry Template](./docs/reference/CHANGELOG_ENTRY_TEMPLATE.md)** — Copy/paste template and writing guidance for entries.
- **[Project Setup Style](./docs/guides/PROJECT_SETUP_STYLE.md)** — Standardized command/process baseline inspired by vercel/ai.
<<<<<<< HEAD
=======
- **[Provider Setup Guide](./docs/guides/PROVIDER_SETUP_GUIDE.md)** — cliproxy login, provider/model routing, adapter vs native behavior, GLM + MiniMax flows, and OpenCode/Zen integration notes.
- **[Domain Mapping Guide](./docs/guides/DOMAIN_MAPPING_GUIDE.md)** — `thegent domain map` advisor mode for Porkbun + Cloudflare Tunnel domain exposure.
- **[Release Supply Chain Controls](./docs/governance/RELEASE_SUPPLY_CHAIN_CONTROLS.md)** — SBOM, vulnerability scans, governance attestation, and release provenance artifacts.
>>>>>>> codex/governance-wireup
=======
>>>>>>> codex/provider-plane-wave1
- **[Architecture Overview](./docs/reference/ARCHITECTURE_LAYERS.md)** — Design layers and internals.
- **[Research Index](./docs/research/RESEARCH_CONSOLIDATED.md)** — Findings and experiments.

---

## 🚢 Docs Deploy

Local docs:

```bash
bun run docs:dev
bun run docs:build
```

GitHub Pages:

- Workflow: `.github/workflows/docs.yml`
- URL convention: `https://<owner>.github.io/thegent/`

---

## 🤝 Contributing

We welcome community contributions! Please see our **[CONTRIBUTING.md](CONTRIBUTING.md)** for:
- Development environment setup (using `uv`).
- Test suite execution (`task test`).
- Coding standards and PR process.

---

## 📜 License

Distributed under the MIT License. See [LICENSE](LICENSE) for more information.

---

<p align="center">
  Built with ❤️ by the community
</p>
