Metadata-Version: 2.4
Name: robert-github-agent
Version: 0.1.0b1
Summary: An AI teammate that takes care of your GitHub work.
Project-URL: Homepage, https://github.com/wklken/robert
Project-URL: Documentation, https://github.com/wklken/robert/tree/main/docs
Project-URL: Issues, https://github.com/wklken/robert/issues
Author: Robert contributors
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Requires-Dist: pyyaml<7,>=6.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pip-audit; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: tomli; (python_version < '3.11') and extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Description-Content-Type: text/markdown

# Robert

[English](README.md) | [简体中文](README_ZH.md)

**Your Repo Teammate**

An AI teammate that takes care of your GitHub work.

Robert is a self-hosted GitHub teammate that turns trusted issues, mentions,
assignments, reviews, and follow-up comments into controlled coding-agent work.
It coordinates local workers, isolates repository work in Git worktrees,
audits proposed GitHub actions, and stores durable workstream state in SQLite.

## What Robert Is

Robert is a local control plane for trusted GitHub collaboration. It discovers
authorized work, routes it to a configured worker, supervises execution, audits
the proposed GitHub actions, and publishes only actions allowed by the route.

## Why Robert Exists

Coding agents are useful, but unattended GitHub automation needs durable state,
clear trust boundaries, isolated workspaces, deduplication, and evidence.
Robert provides those controls without requiring a GitHub App or hosted service.

## Key Capabilities

- Trusted issue, pull-request, review, assignment, and mention handling.
- Multi-repository workstreams stored in SQLite.
- Per-route worker, required-skill, and recommended-skill configuration.
- Isolated Git worktrees for analysis, implementation, and source review.
- Native systemd user services and macOS LaunchAgents.
- Read-only local web UI with an explicitly enabled writable mode.
- Optional read-only OpenClaw chat commands.
- Safe migration from the former `dd-github-agent` state directory.

## How It Works

```mermaid
flowchart LR
    A[Poll GitHub with gh] --> B[Normalize and authorize]
    B --> C[Create or resume workstream]
    C --> D[Resolve route and skills]
    D --> E[Prepare isolated workspace]
    E --> F[Run configured worker]
    F --> G[Audit structured result]
    G -->|Accepted| H[Deduplicate and publish]
    G -->|Blocked| I[Persist failure evidence]
    H --> J[(SQLite state)]
    I --> J
```

Robert polls GitHub through the authenticated `gh` CLI, normalizes events,
checks repository-specific trust rules, creates or resumes a workstream, selects
a route, prepares a task workspace, launches a local worker, audits its
structured result, and deduplicates approved GitHub actions before publication.

## Security and Trust

GitHub text is untrusted input. Only configured actors can trigger work.
Repository overrides cannot change immutable route permissions or workspace
policy. Worker environments use an allowlist, credentials are never stored in
Robert configuration, and GitHub-facing text passes the redaction and audit
gates. The web UI binds to `127.0.0.1` by default.

## Requirements

- Linux or macOS. Windows is supported through WSL.
- Python 3.10 or newer.
- Git and GitHub CLI (`gh`) with an authenticated session.
- At least one local worker command such as Codex.
- `pipx` is recommended for installation.

## Quick Start

```bash
pipx install robert-github-agent
gh auth login
robert init
robert doctor
robert service install
robert service start
```

The configuration is written to `~/.config/robert/config.yml`. Runtime data is
stored under `~/.local/share/robert/`.

## Configuration

Robert uses versioned YAML. Configure the GitHub account, worker definitions,
skill search paths, route overrides, and one or more repository checkouts.
See [docs/reference.md](docs/reference.md#configuration).

## Worker Adapters

Built-in adapters support `codex`, `tcodex`, `cbc`, and a generic `command`
adapter. A worker definition chooses its adapter, executable, default model,
effort, timeout, prompt transport, and environment-variable allowlist.

## Route Skills

Each route can declare required and recommended skills. Missing required skills
block that task before a worktree or worker is created. Missing recommended
skills appear in doctor output but do not block execution.

## Multiple Repositories

Each repository has its own checkout, worktree root, trusted actors, concurrency
limit, and optional route overrides. A failure in one repository does not stop
other repository pipelines in the same cycle.

## Daemon Service

```bash
robert service install
robert service start
robert service status
```

Robert runs in the foreground under systemd user services or launchd. Use
`robert daemon run` for direct foreground operation.

## Local Web UI

```bash
robert web run
```

The default server is local and read-only. Writable mode requires:

```bash
robert web run --writable --operator "$USER"
```

Non-loopback binding also requires `--allow-remote` and an authenticated reverse
proxy.

## OpenClaw

```bash
robert openclaw install
robert openclaw status
```

The optional plugin exposes read-only Robert status, task, run, and artifact
commands. It never schedules or starts Robert.

## Migration

Preview and import legacy state:

```bash
robert migrate dd-github-agent --dry-run
robert migrate dd-github-agent
```

Migration creates a separate backup and preserves legacy deduplication markers.

## Troubleshooting

Run `robert doctor --output json`, check `robert service status`, and export a
redacted support archive with:

```bash
robert diagnostics export --output robert-diagnostics.zip
```

Do not attach private repository content or credentials to public issues.

## Contributing

Read [COMMUNITY.md](COMMUNITY.md), run the documented verification commands,
and sign commits with `git commit -s`. Robert uses the Developer Certificate
of Origin and does not require a CLA for the first beta.

## Project Status

Robert `0.1.0b1` is a public beta. Polling is the only GitHub event transport in
this release. Interfaces may evolve before the first stable release.

## License

Apache License 2.0. See `LICENSE`.
