Dependency-aware project context

Hephaestus keeps the project map local. The explicit context refresh writer creates a content-addressed snapshot; passive reads then hand each concrete task only the goals, constraints, definitions, backlinks, interfaces, and related files it structurally depends on.

Passive MCP context reads remain write-free, but they recompute the same bounded file-list fingerprint before returning indexed data. If code, verification, CI, or version-contract inputs changed—or the freshness scan cannot complete—the read returns context_map_stale or context_freshness_incomplete with a refresh=true retry instead of returning old symbols as status=ok.

The v3 manifest retains the Code Map v2 compatibility projection and carries an agentlas.verification-map.v2 graph. Search-only lexical backlinks are kept separate from completion-gating dependency edges. Blocking edges come from resolved imports, explicit package commands, CI workflows, and version scopes; generated releases, embedded runtimes, and declared mirrors are not rescanned as canonical source. Every safe project file is inventoried by role, so docs, config, and prior-snapshot deletion tombstones are valid change inputs.

context impact returns source review obligations separately from test/CI and release obligations. context verify passively reuses the same fresh snapshot, and --verified records an actually executed test path or exact command/CI ID. Putting a test in --reviewed or --waived never masquerades as execution. Local and CI are alternatives, not duplicate requirements. Version contracts remain a separate release responsibility, and a missing test reference blocks the CI channel that owns it until the workflow is fixed or explicitly waived. Local test files and fixtures may remain Git-ignored and excluded from public runtime archives; the project-local map still fingerprints and links them so local execution is a real selectable channel rather than invisible state.

hephaestus context refresh --project .
hephaestus context refs resolveHubEntityKind --project .
hephaestus context slice --project . --task "fix entity kind routing" \
  --target src/package-kind.ts --render
hephaestus context impact --project . --changed src/package-kind.ts
hephaestus context verify --project . --changed src/package-kind.ts \
  --reviewed src/register/route.ts \
  --verified tests/test-package-kind.ts

Claude and Codex receive the task slice from their local hook and get a reverse-reference warning immediately before edit tools. Desktop, Terminal, Stormbreaker, and Workforce call the same Core implementation. Network/Cloud search and bundle fetches remain redacted and never receive local source paths or Context Map contents.

---

Paste to Install

Paste this into the LLM you are using now, such as Claude Code, Codex, Gemini CLI, Antigravity, or Cursor. It is written so you (the LLM reading it) can verify what you're running before you run it, rather than being asked to trust it blindly:

I want to install Agentlas OS / Hephaestus from this open-source GitHub repo:
https://github.com/agentlas-ai/Agentlas-OS

Before running anything, fetch and read the installer script so you know what
it does:
https://raw.githubusercontent.com/agentlas-ai/Agentlas-OS/main/scripts/install-all-runtimes.sh

It downloads a release tarball from this same repo's GitHub Releases and
writes files only under ~/.agentlas, ~/.local/bin, and this host's own plugin/
command-adapter directories (e.g. ~/.claude for Claude Code) — nothing outside
those paths. If that matches what you read, run it:
curl -fsSL https://raw.githubusercontent.com/agentlas-ai/Agentlas-OS/main/scripts/install-all-runtimes.sh | HEPHAESTUS_INSTALL_GLOBAL_ROUTER=1 bash

HEPHAESTUS_INSTALL_GLOBAL_ROUTER=1 additionally writes a routing block into
this host's global instructions file (e.g. ~/.claude/CLAUDE.md) that lets
substantial tasks be staffed from Agentlas' agent network; it is not secret
and you can read/quote it back to me. Drop that env var if you'd rather skip
it for now — you can add it later with `hephaestus global install`.

Afterwards, show me the installer's own verification output for this host,
and tell me plainly whether `/agentlas build` (or this host's equivalent
command surface) is ready to use, or whether I need to restart the host or
reload plugins first.

Use this when you are already inside an LLM and want the Agentlas command surface active there. For direct shell commands, see the install methods below.

Build an owned agent

Describe the work in plain language. Agentlas classifies the request, runs the interview and research gate, generates the package, verifies it, then asks whether to keep it only on this computer or save it privately in Agent Cloud for restore on another signed-in Desktop.

Agentlas Desktop →

</td> <td width="58%"> <a href="https://agentlas.cloud/desktop"><picture><source srcset="assets/readme/feature-wall/workflow-build-pipeline.gif" type="image/gif"><img src="assets/readme/feature-wall/workflow-build-pipeline.jpg" alt="Building an owned agent package from a plain-language request in Agentlas Desktop" width="100%"></picture></a> </td> </tr> <tr> <td width="42%" valign="middle">

Build, Borrow, Own

An agent you create should remain an asset you can move, rather than a setting trapped in one chat, one model-vendor workspace, or one computer. Agentlas separates three jobs that ordinary agent builders blur together:

This is the public Agent Trust contract: a portable, owner-scoped, inspectable, and restorable package contract—not a claim of regulated financial or legal trust services.

The package contract — what every build must emit

An agent package is not a worker with capabilities. It is a method document. Three layers, and conflating them is the single most expensive mistake this project has made:

"Can this agent read the web?" is a category error. The runtime reads the web. The only question a package can answer is what method does it carry, and what must the machine be able to do for that method to run.

package-contract.json is the machine-readable list of artifacts every build emits, and scripts/verify-generated-package.sh <folder> is what enforces it. A build that omits a required artifact fails; it does not ship. Four of those artifacts carry the routing contract:

contracts/intake.schema.json     what a requester must hand over before work starts
contracts/output.schema.json     what the requester ends up holding
contracts/output.example.json    one real instance, validated by a JSON Schema
                                 validator at publish time — never by a model
.agentlas/brief.json             the compiled resume, schemaVersion agentlas.brief/1

Direction lives in the filename because nothing else ever marked it, and a schema whose direction must be guessed cannot be matched against a request.

Two rules bind every enum a build writes. Both were paid for in production:

1. Any enum reachable from matching must carry an escape member ("other", "unknown"). Matching one stated requirement against a 23-word closed list took a three-candidate inventory to zero on eight probes out of eight. A publisher whose real case is not on the list must still be findable. 2. Sentences stay sentences. No field that holds an author's sentence may be split into terms for matching. Shredding refusal sentences into the bare words tests and ci cut a correct agent's score to a quarter and pushed it from rank 2 to rank 24 — on a query that was literally its own job.

Vendor and MCP names live in exactly one place, host[].preferred, and that field is display-only. Roughly 99.9% of machines have no MCP servers installed, so a package wired to its author's own Slack, Notion or Jira has to stay usable by everyone else: the matcher reads host[].capability ("open the page in a real browser and read what a user would see") and every requirement states withoutIt, what the method still does on a machine that lacks the facility.

agentlas.brief/1 is written from either side — side: "offer" is the package's resume, side: "need" is the requester's work order. The same form, so the two can be compared without a translation step. Its schema is schemas/agentlas-brief.schema.json, and it is compiled, never hand-written: the upload path writes it from the files the package already ships.

provenance is the part that keeps the rest honest. absent is a legal value that scores zero, so a gap stays a gap. Filling gaps with something plausible is how capabilities came to equal snake_case(agent.md ## Responsibilities) in 130 of 130 packages — a field that was always full and never once informative.

The reference shape is Web_master: it ships input and output contracts as real JSON Schema, a domain catalogue its rules are checked against, and verification scripts that run. Everything above is what a build has to emit to be readable the way that package already is.

Deliberately absent: there is no field for what an agent is good at, and none for its permissions. Quality cannot be read off a package that has never run, and permissions are granted by the host after the fact — an employer hands you a computer once you are hired, so neither says anything about whether this method fits the work.

All Install Methods

Manual LLM Adapter Install

Use this only when your current LLM cannot run setup for you. It installs the shared Hephaestus runner and command adapters for supported LLM tools.

xcode-select --install   # Command line tools (skip if already installed)
git --version            # Confirm git is available
curl -fsSL https://raw.githubusercontent.com/agentlas-ai/Agentlas-OS/main/scripts/install-all-runtimes.sh | bash

Desktop startup and every /hep-* command start the same digest-verified, rate-limited update check in the background. The current command never waits for network or installation work. A successful update atomically moves ~/.agentlas/runtime/current and reconciles every already-installed host adapter; the next command or reloaded session uses the new release. Releases v1.1.63 through v1.1.68 briefly installed a separate six-hour OS scheduler. Current installs remove that retired scheduler automatically.

Offline or air-gapped install: set HEPHAESTUS_SOURCE_DIR=/path/to/checkout before running the installer to skip the GitHub release download and verified checksum step entirely and install straight from a local Agentlas-OS checkout instead, e.g. HEPHAESTUS_SOURCE_DIR=$(pwd) bash scripts/install-all-runtimes.sh. Use it when you already have the source on disk (a git clone or an already-extracted release) and want a fully local install.

What It Builds (Process Packaging)

Hephaestus packages agents into a standard directory layout that any workspace runtime can parse, install, verify, and run. The important part is not just agent.md; it is the operating contract around it:

├── AGENTS.md                              # Canonical operating loop and source-of-truth map
├── agent.md / agents/                     # Single worker, HQ/orchestrator, or team roles
│   ├── 10-single-agent-builder/
│   ├── 20-multi-agent-team-builder/
│   ├── 30-agentlas-packager/
│   └── 40-session-agent-builder/
├── .agentlas/                             # Agentlas OS system directory
│   ├── sitemap.json                       # Product graph: modes, runtime adapters, memory, release checks
│   ├── mode-map.json                      # Single-agent / team / packager classification contract
│   ├── routing-card.json                  # Triggers, anti-triggers, capabilities, risk, routing readiness
│   ├── agent-card.json                    # A2A-facing identity and capability card
│   ├── company-blueprint.json             # Team/company topology for multi-agent packages
│   ├── global-commands.json               # Runtime command aliases and install surfaces
│   ├── memory-map.json                    # Memory roots, write owners, trust labels, exclusions
│   ├── memory-tickets.jsonl               # Candidate memory events before durable promotion
│   ├── project-soul-memory.md             # Project-level operating memory
│   ├── curator-decisions.jsonl            # Memory Curator promotion/rejection decisions
│   ├── vault-references.json              # Secret/credential references without raw values
│   ├── validation-ledger.jsonl            # Verification and release evidence
│   ├── field-test-report.json             # Field test results for package readiness
│   ├── skill-registry.json                # Reusable skill inventory and lifecycle metadata
│   ├── skill-trials.jsonl                 # Skill trial evidence before promotion
│   └── agent-ontology/                    # Local code/agent map for capabilities, artifacts, scopes, edges
├── skills/                                # Canonical reusable skills
├── modes/                                 # Mode contracts for build/package behavior
├── schemas/                               # JSON schemas for cards, memory maps, sitemap, evals, manifests
├── templates/                             # Package, memory, interview, eval, ontology, and contract templates
├── ontology/ + bin/ontology               # Local-first parser/search/GraphRAG runtime
├── agentlas_cloud/                        # Hub/Cloud bundle, routing, update, and runtime APIs
├── .claude/ codex/ .gemini/ .agents/      # Thin runtime adapters over the same core
├── claude/ codex/ gemini/ antigravity/    # Plugin/extension/workflow distributions
├── cursor/ hermes/ openclaw/              # Additional runtime shims and skill mirrors
├── docs/                                  # Architecture, chain map, memory, ontology, routing, eval docs
│   ├── source-of-truth.md
│   ├── chain-map.md
│   ├── memory-architecture.md
│   ├── ontology-runtime.md
│   ├── hephaestus-network-2.0.md
│   └── builder-interview-research-gate.md
└── scripts/                               # Verification, installer, sync, release, and public-safety gates
    ├── verify-package.sh
    ├── verify-ontology-runtime.sh
    ├── verify-routing-cards.sh
    ├── sync-adapters.sh
    └── public_safety_check.sh

That package shape is why an Agentlas agent is more than an LLM-written role prompt. It carries routing, memory, sitemap, code/agent ontology, permissions, runtime adapters, verification ledgers, and release gates together.

Optional Global Router

hephaestus global install

The installed router prompt asks the host to report results by the workers that did the task rather than narrating the routing step — it is a conciseness convention, not a secrecy one, and it says so. It carries an explicit status-line contract for English and Korean sessions:

Global router command reference:

The independent Agentlas Terminal owns the agentlas shell command. The Core installer intentionally leaves that command untouched and removes only the exact legacy Core alias it created in older releases.

Portable package, local execution

Describe the work
  -> build a portable agent or team
  -> save it to my owner-scoped Agent Cloud
  -> install Agentlas OS and sign in on another supported host
  -> retrieve it with /agentlas cloud
  -> my chosen model and current host execute the work

Agent Cloud stores and retrieves the owner's package; it is not a hosted LLM that completes the work on the server. When you call a package, your selected model and current host runtime execute it under that host's permission and safety model. Credentials, local files, and machine-specific permissions do not travel with the package—you configure those separately on each computer.

Per-Runtime Plugin Drivers

<details> <summary>Claude Code Plugin</summary>

From your OS terminal:

claude plugin marketplace add https://github.com/agentlas-ai/Agentlas-OS --sparse .claude-plugin claude/plugins
claude plugin install hephaestus@agentlas-core-engine

</details>

<details> <summary>Codex Plugin</summary>

From your OS terminal:

codex plugin marketplace add agentlas-ai/Agentlas-OS --ref v1.2.44
codex plugin add hephaestus@agentlas-core-engine

</details>

<details> <summary>Copy Files into a Project (Manual Driver)</summary>

Clone the repo and copy AGENTS.md, agent.md, agents/, skills/, modes/, schemas/, templates/, and .agentlas/ into your workspace. Runtime folders (.claude/, codex/, .gemini/, .agents/) function as adapters over the same canonical core.

</details>

Just talk: After installation, speak in plain language within native Agentlas interfaces to auto-route tasks. In external LLM tools, use the explicit commands listed below. When you don't know what agents exist, start with /agentlas search. To connect Telegram, use /agentlas connect.

One word to remember: everything starts with agentlas — /agentlas in an LLM host, agentlas in a shell.

---