{"id":48802986,"url":"https://github.com/wordbricks/codex-virtual-assistant","last_synced_at":"2026-04-16T06:04:28.593Z","repository":{"id":348155142,"uuid":"1195859458","full_name":"wordbricks/codex-virtual-assistant","owner":"wordbricks","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-08T10:09:59.000Z","size":36994,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-08T10:26:48.562Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wordbricks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-30T06:11:52.000Z","updated_at":"2026-04-08T10:09:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/wordbricks/codex-virtual-assistant","commit_stats":null,"previous_names":["wordbricks/codex-virtual-assistant"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/wordbricks/codex-virtual-assistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wordbricks%2Fcodex-virtual-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wordbricks%2Fcodex-virtual-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wordbricks%2Fcodex-virtual-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wordbricks%2Fcodex-virtual-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wordbricks","download_url":"https://codeload.github.com/wordbricks/codex-virtual-assistant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wordbricks%2Fcodex-virtual-assistant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31781292,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T02:24:21.117Z","status":"ssl_error","status_checked_at":"2026-04-14T02:24:20.627Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-14T04:01:06.175Z","updated_at":"2026-04-14T04:01:07.070Z","avatar_url":"https://github.com/wordbricks.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Codex Virtual Assistant (CVA) [/ˈsiːvə/]\n\nCodex Virtual Assistant is a WTL GAN-policy based web personal virtual assistant for browser-centric office work. The product source of truth is [PRD.md](/Users/dev/git/CodexVirtualAssistant/PRD.md); code under `specs/` remains reference material only.\n\nThis repository now includes the first runnable product foundation outside `specs/`:\n\n- `cmd/cva` provides the main CLI, including `cva start` for the local HTTP server.\n- `internal/assistant` defines shared run, task, attempt, evaluation, artifact, evidence, and wait-state types, plus `TaskSpec` normalization defaults.\n- `internal/assistantapp` owns background run creation, status lookup, resume/input, and cancel orchestration over the engine and store.\n- `internal/prompting` defines the planner and evaluator JSON contracts plus strict output decoding.\n- `internal/store` owns the local SQLite schema and repository methods for runs, events, attempts, artifacts, evidence, evaluations, tool calls, web steps, and wait requests.\n- `internal/wtl` now contains the core run engine plus a concrete Codex-oriented runtime that maps agent-browser style execution traces into persisted tool calls, browser steps, evidence, and screenshot artifacts.\n- `internal/api` now exposes the run lifecycle routes and an SSE event stream backed by persisted run events and a live event broker.\n- `internal/config`, `internal/app`, and `internal/policy/gan` establish the product bootstrap and lifecycle policy package layout.\n- `web/` now contains the embedded operator UI shell served by the app.\n\n## Agent Bootstrap\n\nCopy and paste this instruction to your favorite coding agent to start.\n\n```text\nClone this repository, install prerequisites, build it, and run it locally.\n\n1. Clone the repository and enter it:\n   - Repository URL: https://github.com/siisee11/CodexVirtualAssistant\n   - git clone git@github.com:siisee11/CodexVirtualAssistant.git\n   - cd CodexVirtualAssistant\n\n2. Install prerequisites:\n   - Install Go 1.26 or newer.\n   - Install Node.js 20.19.0 or newer (or Node.js 22.12.0+) for the webapp toolchain.\n   - Install sqlite3 and make sure it is on PATH.\n   - Install `ffmpeg` and make sure it is on PATH. CVA uses it to turn captured browser frames into the report video replay.\n   - Install the codex CLI and authenticate it so `codex app-server` can run.\n   - Install the `agent-browser` CLI and browser runtime:\n     - npm install -g agent-browser\n     - agent-browser install\n\n3. Build the CLI binary:\n   - mkdir -p dist\n   - go build -o dist/cva ./cmd/cva\n\n4. Start the app:\n   - ./dist/cva start\n   - or run with full Codex filesystem access: ./dist/cva start --yolo\n\n5. Open the UI:\n   - http://127.0.0.1:8080\n```\n\nYou can also install the CLI from npm:\n\n```bash\nnpm install -g @wordbricks/cva\ncva version\n```\n\nThe npm package name is scoped because the unscoped `cva` package is already taken on npm. The installed command is still `cva`, and installation downloads the native binary for the current platform from GitHub Releases.\n\n## Install and Use\n\nInstall from npm:\n\n```bash\nnpm install -g @wordbricks/cva\n```\n\nOr build from source:\n\n```bash\ngit clone git@github.com:wordbricks/codex-virtual-assistant.git\ncd codex-virtual-assistant\ngo build -o dist/cva ./cmd/cva\n./dist/cva version\n```\n\nStart the local server:\n\n```bash\ncva start\n```\n\nStart it as a background daemon:\n\n```bash\ncva start --daemon\n```\n\nStart with full Codex filesystem access:\n\n```bash\ncva start --yolo\n```\n\nThen open `http://127.0.0.1:8080`.\n\nDaemon logs are written to `workspace/logs/cva.log` by default, and the PID file is stored at `workspace/cva.pid`.\n\nBasic CLI usage:\n\n```bash\ncva version\ncva upgrade\ncva start --daemon\ncva logs\ncva logs --follow\ncva stop\ncva run \"Summarize today's work\"\ncva status \u003crun_id\u003e\ncva watch \u003crun_id\u003e\ncva list\ncva chat \u003cchat_id\u003e\ncva cancel \u003crun_id\u003e\ncva resume \u003crun_id\u003e key=value\n```\n\nFor scheduled work:\n\n```bash\ncva schedule list\ncva schedule show \u003cscheduled_run_id\u003e\ncva schedule cancel \u003cscheduled_run_id\u003e\n```\n\n## Run locally\n\n```bash\ngo run ./cmd/cva start\n```\n\nThen open `http://127.0.0.1:8080`.\n\nTo run the server in the background during development:\n\n```bash\ngo run ./cmd/cva start --daemon\ngo run ./cmd/cva logs --follow\ngo run ./cmd/cva stop\n```\n\nTo force the Codex app server to run with `danger-full-access`, start the server with:\n\n```bash\ngo run ./cmd/cva start --yolo\n```\n\nThe server now uses `codex app-server` as the default execution runtime for planner/generator/evaluator phases. Make sure the `codex` CLI is installed, authenticated, and able to run `codex app-server` on your machine before you start a run from the UI.\n\nInstall `agent-browser` on the same machine so Codex can execute browser work through the current CLI:\n\n```bash\nnpm install -g agent-browser\nagent-browser install\n```\n\nIf you want browser activity to appear as an embedded replay video in the final supervisor report, `ffmpeg` must also be installed and available on `PATH`.\n\nEnvironment variables:\n\n- `ASSISTANT_HTTP_ADDR`: override the listen address, default `127.0.0.1:8080`\n- `ASSISTANT_DATA_DIR`: root directory for local state, default `./workspace`\n- `ASSISTANT_PROJECTS_DIR`: project workspace root, default `\u003cdata dir\u003e/projects`\n- `ASSISTANT_DATABASE_PATH`: SQLite database path, default `\u003cdata dir\u003e/assistant.db`\n- `ASSISTANT_ARTIFACT_DIR`: directory for generated artifacts, default `\u003cdata dir\u003e/artifacts`\n- `ASSISTANT_MAX_GENERATION_ATTEMPTS`: default generator retry budget, default `3`\n- `ASSISTANT_CODEX_BIN`: Codex CLI path, default `codex`\n- `ASSISTANT_CODEX_CWD`: working directory given to Codex app server, default current repo root\n- `ASSISTANT_CODEX_APPROVAL_POLICY`: Codex approval policy, default `never`\n- `ASSISTANT_CODEX_SANDBOX`: Codex sandbox mode, default `workspace-write`\n- `ASSISTANT_CODEX_NETWORK_ACCESS`: outbound network access for Codex workspace-write turns, default `true`\n\n## Current scope\n\nCurrent completed foundation:\n\n- local config loading and validation\n- data directory and SQLite-path bootstrapping\n- TaskSpec normalization and planner JSON contracts\n- SQLite-backed persistence for the core run records\n- WTL lifecycle orchestration for planner, generator, evaluator, retry, waiting, resume, and cancel flows\n- Codex-style runtime mapping for browser-oriented evidence, tool activity, and screenshot artifacts\n- run lifecycle HTTP routes and SSE event streaming\n- a usable web UI skeleton for starting tasks, following live progress, reviewing evidence and artifacts, and handling waiting states\n\n## Using the web UI\n\nOpen `http://127.0.0.1:8080`, describe the task in plain language, and start the run from the top form.\n\nThe page then keeps a single run view updated through the run status API and SSE stream:\n\n- current task summary and status\n- live progress timeline\n- recent browser and tool activity\n- collected evidence and generated artifacts\n- waiting cards for approvals, clarification, or authentication\n\n## Runtime behavior\n\nCurrent local runtime behavior:\n\n- the app boots a single-user local server with embedded static assets\n- run state is stored in SQLite and created automatically on startup\n- the default shipped executor starts `codex app-server` and runs each phase through a real Codex turn\n- the product does not call `agent-browser` itself; Codex chooses and invokes available tools during the turn, and the app maps resulting tool, command, and browser-like events back into persisted evidence\n- runs move through `queued`, `planning`, `generating`, `evaluating`, `waiting`, and terminal states while persisting attempts, events, evidence, tool calls, browser steps, evaluations, and artifacts\n- app-server approval or user-input requests are converted into product-level `waiting` states until the operator resumes the run with approval or missing context\n\nLocal state locations:\n\n- SQLite database: `data/assistant.db` by default\n- generated artifacts directory: `data/artifacts` by default\n\n## Validation\n\nUseful local verification commands:\n\n```bash\nGOCACHE=/tmp/cva-go-build go test ./cmd/cva ./internal/... ./web\nnode --check web/static/app.js\n```\n\n## npm release\n\nThe repository now includes an npm wrapper package in [`npm/`](/Users/dev/git/codex-virtual-assistant/npm) for `@wordbricks/cva`.\n\nRelease flow:\n\n1. Configure npm Trusted Publishing for this GitHub repository once.\n2. Push a semver tag like `v0.1.0`.\n3. The GitHub Actions workflow at [release.yml](/Users/dev/git/codex-virtual-assistant/.github/workflows/release.yml) will:\n   - run verification\n   - build native `cva` binaries for supported platforms\n   - upload them to the GitHub release for that tag\n   - publish `@wordbricks/cva` to npm with provenance\n\nThe npm package installs the `cva` command and downloads the matching native binary asset from the GitHub release for the package version.\n\nFor the first manual CLI-driven publish:\n\n```bash\nnpm login\nmake release VERSION=0.1.0\n```\n\nIf you want the individual steps instead:\n\n```bash\nmake release-manual VERSION=0.1.0\nmake release-tag VERSION=0.1.0\nmake release-gh VERSION=0.1.0\nmake release-npm\n```\n\n## HTTP API\n\n- `POST /api/v1/runs`\n- `GET /api/v1/runs/:id`\n- `GET /api/v1/runs/:id/events`\n- `POST /api/v1/runs/:id/input`\n- `POST /api/v1/runs/:id/resume`\n- `POST /api/v1/runs/:id/cancel`\n\n## Local requirements\n\n- Go 1.26+\n- Node.js `^20.19.0 || \u003e=22.12.0` for the `webapp/` Vite toolchain\n- `codex` CLI installed and authenticated; the default runtime shells out to `codex app-server`\n- `agent-browser` CLI installed and initialized with `agent-browser install`\n- `sqlite3` available on the local machine; the current repository layer uses the system SQLite CLI for local persistence in this sandboxed environment\n- `ffmpeg` available on the local machine; browser-session report videos are generated only when `ffmpeg` is present on `PATH`\n- The npm CLI wrapper in `npm/` remains compatible with Node.js 18+, but repository development now assumes the webapp runtime above\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwordbricks%2Fcodex-virtual-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwordbricks%2Fcodex-virtual-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwordbricks%2Fcodex-virtual-assistant/lists"}