Asist

Asist - экспериментальный service-first плагин для оркестрации агентной разработки. Он ведет artifact-first run state, мастер запуска, сбор бизнес-требований, независимые tools, review/validation loop, derived memory, очередь subagent-задач и UI workflow для системной frontend-работы.

Проект намеренно local-first. Markdown и JSON artifacts являются источником истины; SQLite используется только как derived cache/index. External workers, reviewers, commits, pushes, deploys, credentials и live infrastructure actions остаются за явными gates.

Статус

Asist - ранний OSS-проект, выделенный из персонального Codex workflow.

• Public API stability: experimental.
• Runtime dependencies: Python standard library для core service/CLI.
• Optional sidecar: Rust binary для быстрого indexing/fingerprinting.
• External integrations: OpenCode, Claude Code, OmniRoute и Codex plugin installation подключаются оператором.

Возможности

• Loopback HTTP service: scripts/asistd.py.
• Operator CLI: scripts/asistctl.py.
• Artifact-first run state under a configurable run root.
• Run OS artifacts: RUN_EVENTS.jsonl, RUN_TIMELINE.md, RUN_INSPECT.json.
• Четыре native surface profiles для мастера запуска: codex, claude, zed, generic.
• Launch/business/plan gates before implementation.
• Brainstorm, plan, build, review, validation, queue, and browser-space skills.
• UI orchestrator for global-first UI changes: tokens -> styles -> components -> layouts -> pages -> app.
• Derived memory layer with redacted SQLite indexing and review-cache hints.
• Controlled frontier scheduler with explicit task run/merge operations.
• Optional Rust sidecar for file inventory and fingerprints.

Native Surface Profiles

Asist master может стартовать в одном из четырех surface state:

• codex: основной режим для Codex dialog и browser companion. Click actions идут напрямую в loopback asistd HTTP API, без CLI-per-click.
• claude: режим для Claude dialog/brief. Native command contract: /Users/avm/.local/bin/claude -p --output-format stream-json --brief --model opus --effort xhigh; --chrome добавляется только когда запросу реально нужен browser.
• zed: режим для Zed Agent Panel через zed-codex-acp. Это ACP/artifact handoff и opening workflow, не pixel/UI automation и не чтение Zed secrets.
• generic: fallback для explicit asistctl или HTTP caller.

Каждый run пишет SURFACE_PROFILE.*, MASTER_STATE.* и MASTER_ACTIONS.json. Normal approvals могут приходить от surface authority, но push, deploy, credentials и live infra всегда требуют отдельный high-risk gate artifact.

Repository Layout

asist/                  Python package: contracts, tools, orchestrators, service
scripts/                asistd.py and asistctl.py entrypoints
skills/                 Codex skill definitions
references/             Design and operational references
review-packs/           Review guidance packs
sidecars/asist-sidecar/ Optional Rust sidecar
tests/                  unittest suite

Быстрый Старт

Clone the repository:

git clone https://github.com/Mesteriis/asist.git
cd asist

Run local checks:

python3 -m unittest discover -s tests
python3 -m compileall -q asist scripts tests
cargo test --manifest-path sidecars/asist-sidecar/Cargo.toml

Start the service:

python3 scripts/asistd.py serve --host 127.0.0.1 --port 8765

Create and inspect a run:

python3 scripts/asistctl.py run create \
  --repo "$PWD" \
  --request "Plan a small safe change" \
  --mode plan \
  --surface codex

python3 scripts/asistctl.py run inspect --run-id "<run-id>"
python3 scripts/asistctl.py run timeline --run-id "<run-id>"
python3 scripts/asistctl.py surface list

Установка Codex Plugin

This repository is a Codex plugin source tree. A personal Codex marketplace entry should point asist to the cloned path, then the plugin can be installed from that marketplace:

codex plugin add asist@personal

The exact marketplace file location is local to a Codex installation. This repository does not commit user-specific marketplace state.

Optional Rust Sidecar

Build the sidecar:

cargo build --release --manifest-path sidecars/asist-sidecar/Cargo.toml

Use it from Asist:

ASIST_SIDECAR_BIN="$PWD/sidecars/asist-sidecar/target/release/asist-sidecar" \
  python3 scripts/asistctl.py tool run --run-id "<run-id>" --tool-id project-intake

If the sidecar is absent or returns invalid output, Asist falls back to rg or Python file walking.

Security Model

• Do not store secrets in run artifacts.
• Do not commit local Codex caches, run directories, .env files, or credential material.
• ASIST_OMNIROUTE_API_KEY and other credentials are operator-provided and must stay outside the repository.
• Browser-space/UI actions are companion surfaces, not approval authorities.
• Push, deploy, credential, and live infrastructure actions require explicit operator approval outside the browser companion.

See SECURITY.md for vulnerability reporting and supported versions.

Third-Party Skill Sources

Some UI skill guidance is rewritten from public skill repositories. Upstream provenance is tracked in references/ui-upstream-sources.md and summarized in THIRD_PARTY_NOTICES.md.

Contributing

Contributions are welcome if they preserve the artifact-first contract and keep external execution gated. Start with CONTRIBUTING.md.

License

Asist is released under the MIT License. See LICENSE.