Agent OS v2.5.3

Agent OS is an engineering operating system for coding agents. Install it once in a VS Code workspace, then use natural prompts for audits, bug fixes, enhancements, tests, and project onboarding.

It keeps enterprise governance, traceability, certification, and knowledge evolution available behind a simple CLI experience.

Install In 2 Minutes

npm install -g @adityaaria/agent-os
cd /path/to/your/workspace
agent-os install
agent-os bootstrap
agent-os status

Agent OS looks for .code-workspace files, asks you to choose or create one, detects projects, generates workspace intelligence, and installs the runtime into .agent-os-workspace/. The installer writes a local runtime registry at .agent-os-workspace/runtime.json and marks that workspace active in the user config registry. agent-os bootstrap then runs analysis, verification, context generation, and context verification in one step.

For CI or scripted installs:

agent-os install --workspace-file ./my-project.code-workspace

The workspace file is mandatory. In non-interactive mode, install fails clearly when --workspace-file is missing.

Legacy initialization remains available for backward compatibility:

agent-os init --workspace-file ./my-project.code-workspace

For installer development and tests only:

agent-os install --target ./sandbox --allow-target-install

First Audit

After installation, open your coding agent in the workspace and run:

AUDIT: Request Leave

Agent OS routes the request through compliance gates, project knowledge, traceability, quality gates, and reporting standards.

First Bug Fix

BUG: Upload photo gagal

Bug fixes require root cause analysis, traceability, regression checks, and quality-gate evidence.

First Enhancement

ENHANCEMENT: Tambah export PDF

Enhancements preserve architectural boundaries, require tests, and trigger knowledge evolution when project behavior changes.

Governance Modes

Agent OS defaults to Standard.

• Light: Fast and simple.
• Standard: Recommended.
• Enterprise: Full governance and certification.

The enterprise capability remains installed; the default UX stays focused on getting developers productive quickly.

Optional Integrations

No integration is required during install.

Configure Telegram later:

agent-os integration telegram

Other integration entry points are reserved for future use:

agent-os integration slack
agent-os integration github
agent-os integration jira

Daily Commands

agent-os bootstrap
agent-os status
agent-os info
agent-os version
agent-os workspace
agent-os doctor
agent-os examples

status shows the active workspace, project count, mode, and integration state. info shows framework version, skills, and core standards. version shows the active runtime version. doctor validates the installed runtime only; use agent-os validate for Agent OS repository/framework validation.

Workspace resolution uses this priority:

1. --workspace <file-or-name>
2. Global active workspace registry
3. Local .agent-os-workspace/runtime.json
4. Current directory upward detection
5. Interactive workspace selection when available

Switch the active workspace:

agent-os workspace
agent-os workspace use hc-leave

Upgrade the active workspace runtime:

agent-os update --dry-run
agent-os update
agent-os update --force

agent-os update creates a backup before overwriting runtime files. --dry-run previews the upgrade without writes. --force overwrites runtime files without the safe-mode backup.

Advanced Usage

Preview deterministic skill routing:

agent-os orchestrate "BUG: Fix auth leak, audit auth, then write selenium e2e tests"

Prepare an AI-agnostic execution package and import the agent result:

agent-os runtime-check
agent-os run audit
agent-os run-status <execution-id>
agent-os result-import <execution-id> ./AI_RESULT.md
agent-os result-validate <execution-id>
agent-os run-list

agent-os run generates AI handoff files, output contracts, result templates, workflow artifacts, and execution history under .agent-os/runtime/. Agent OS does not call AI providers or perform reasoning; any agent can consume the handoff package and return AI_RESULT.md.

Create a run directory:

agent-os orchestrate --run-root .agent-os/runs "ENHANCEMENT: Add CSV export"

Update and inspect run state:

agent-os run-step --run-dir .agent-os/runs/<run-id> --step 1 --status running
agent-os run-status --run-dir .agent-os/runs/<run-id>
agent-os run-status --run-dir .agent-os/runs/<run-id> --format csv
agent-os run-list --run-root .agent-os/runs
agent-os run-list --run-root .agent-os/runs --format csv

Export reports:

agent-os report-export --run-root .agent-os/runs --format csv --output reports/runs.csv
agent-os report-export --run-root .agent-os/runs --channel-config .agent-os/project/report-channels.json --channel spreadsheet
agent-os report-notify --run-root .agent-os/runs --channel-config .agent-os/project/report-channels.json --channel telegram --dry-run
AGENT_OS_TELEGRAM_BOT_TOKEN=... AGENT_OS_TELEGRAM_CHAT_ID=... agent-os report-notify --run-root .agent-os/runs --channel-config .agent-os/project/report-channels.json --channel telegram --send

report-channels.json keeps spreadsheet and Telegram reporting configuration. Tests and local adapters can use mockRequestFile to capture Telegram request payloads without live network calls.

Development Validation

For framework changes:

npm run sync:runtime
npm test
npm run validate
npm run quality
npm run pack:verify

Troubleshooting

• ✖ Error: --workspace-file is required in non-interactive mode. Run interactively or pass --workspace-file ./my-project.code-workspace.

• Agent OS installation not found from this directory. Run commands from the workspace root or reinstall with agent-os install.

• Agent ignores project rules. Run agent-os doctor, then repair with agent-os install --workspace-file ./my-project.code-workspace --force.