Related Pages

Related topics: Multi-Package Architecture, Agents, Commands, Skills & Workflows

Overview & Installation

Project Overview

Liteagents is a lightweight memory and feedback-capture layer that sits alongside AI coding assistants. It is not a model or an orchestrator; it observes the interaction between a user and a coding agent, extracts two kinds of signals — friction events (moments where the user pushes back, corrects, or re-states intent) and remembered preferences (durable rules and conventions) — and routes those signals back into the agent as context for future sessions.

The project is distributed as a single npm package so it can be installed once per machine and reused across multiple agent front-ends. As of the v2.9.0 release, the same memory pipeline runs against four supported tool packages: claude, opencode, ampcode, and droid (Source: package.json:1-40). This cross-tool symmetry is a deliberate design property: a correction learned while working with one assistant can be replayed when the user later switches to another, because all four packages share the same antigen-extraction logic.

The high-level data flow is:

user speaks → agent responds → liteagents observes
            → friction is clustered → antigens written to memory
            → /remember injects antigens into the next prompt

The v2.9.0 redesign specifically changed how antigens are seeded so they are derived from what the user actually said (content and phrase overlap) rather than from machine proxies (Source: README.md:1-60). This keeps memory faithful to user intent across tool boundaries.

Installation

The recommended install path is through npm, which pulls the CLI, the postinstall hooks, and the four tool packages in one step:

npm install -g liteagents

The package.json declares the four tool packages as dependencies (Source: package.json:24-39), so a single global install provisions all supported environments. After install, the liteagents binary becomes available on PATH and is wired up by cli.js, which keeps dispatch thin and delegates heavy lifting to the tool packages and the shared memory engine (Source: cli.js:1-30).

A postinstall.js script runs automatically after the package is unpacked (Source: postinstall.js:1-30). Its job is to verify that the target tool environments are reachable, create the on-disk memory directory layout, and seed default configuration if none exists. If any step fails, the install aborts rather than leaving a half-configured system. The installer is idempotent: re-running npm install -g liteagents will not duplicate memory entries or tool registrations (Source: postinstall.js:20-30).

For users who prefer not to install globally, the same package can be invoked through npx liteagents …, which still triggers postinstall.js on first use.

Supported Tool Packages

The four tool packages each wrap the same core memory engine but expose tool-specific entry points (slash commands, hooks, or CLI shims) so the agent can call into liteagents naturally.

Because all four packages share the same extraction logic, a friction event captured in Claude can surface as a remembered rule inside OpenCode on the next session. The detailed installer guidance for registering, unregistering, and troubleshooting individual tool packages is documented separately (Source: docs/INSTALLER_GUIDE.md:1-40).

First-Run Setup

After installation, run:

liteagents init

init walks through three steps:

1. Detect which of the four supported tools are installed locally and register the matching tool package.
2. Create the memory store directory (default: ~/.liteagents/memory) and initialize the hot/cold split used by the friction → remember pipeline.
3. Print a short summary of registered tools and the resolved paths to the antigen and rule stores.

Memory files are stored as plain JSON under the resolved store path, which makes them inspectable and version-controllable if a user wants to audit or hand-edit them (Source: docs/INSTALLER_GUIDE.md:20-60).

A few operational notes worth keeping in mind on first run:

• If a user only works with one tool, the others can be skipped or disabled later through per-tool configuration without affecting the shared memory core.
• For users upgrading from a pre-v2.9.0 install, the redesigned pipeline applies automatically — no separate migration command is required, but stale machine-proxy antigens from older sessions can be cleared by re-running /friction against recent sessions so the new user-said clustering takes over.
• All CLI subcommands (init, friction, remember, and any tool-package commands) route through the single cli.js entry point, so behavior is consistent regardless of which tool originally triggered the call (Source: cli.js:10-30).

Once init completes, the system is ready: friction events begin populating the antigen pool on the next session, and /remember (or the tool-package equivalent) can be invoked to query or inject remembered rules into the active agent prompt.

Related Pages

Related topics: Overview & Installation, Agents, Commands, Skills & Workflows

Multi-Package Architecture

The liteagents project distributes its agent tooling as four parallel "tool packages" — claude, opencode, ampcode, and droid — and ships a single installer + validation pipeline that targets all of them uniformly. This page describes the structure and the cross-package invariants that keep them in lockstep.

Package Layout and Purpose

The repository supports four downstream tools. The latest release (v2.9.0) describes changes as *"applied identically across all four tool packages (claude, opencode, ampcode, droid)"*, which establishes the central architectural contract: every per-tool adaptation lives behind a shared kernel rather than four divergent implementations.

The four packages cover:

A shared installer/ subsystem is responsible for placing the right assets into each target environment. Source: installer/installation-engine.js (entry point that dispatches per-tool installs).

Installer Subsystem

The installer/ directory is the operational core of the multi-package architecture. It is decomposed by responsibility rather than by tool, which is how the "identical changes" guarantee is enforced:

• installation-engine.js — top-level driver; chooses which packages to install and in what order. Source: installer/installation-engine.js.
• package-manager.js — per-tool resolution, dependency handling, and version pinning per package. Source: installer/package-manager.js.
• path-manager.js — computes filesystem locations (config, memory, agent data) per target package, isolating them so packages don't trample each other. Source: installer/path-manager.js.
• verification-system.js — post-install checks; verifies each package's invariants independently before declaring success. Source: installer/verification-system.js.
• report-template.js — formats the human-readable install / verify report; identical structure across all four packages. Source: installer/report-template.js.

flowchart LR
  A[installation-engine.js] --> B[package-manager.js]
  A --> C[path-manager.js]
  A --> D[verification-system.js]
  D --> E[report-template.js]
  B --> P1[claude]
  B --> P2[opencode]
  B --> P3[ampcode]
  B --> P4[droid]
  C --> P1
  C --> P2
  C --> P3
  C --> P4
  D --> P1
  D --> P2
  D --> P3
  D --> P4

Cross-Package Invariants

The v2.9.0 redesign of the /friction → /remember memory pipeline is the clearest demonstration of the architecture's purpose. The release notes state that antigens *"stop poisoning hot memory and antigens come from what the user actually said"* and that the redesign was *"applied identically across all four tool packages"*. Operationally this means a single behavioral change — how the memory pipeline seeds antigens — propagates to claude, opencode, ampcode, and droid without per-package forks.

The invariant set enforced by this layering:

1. Single source of truth for memory behavior. Pipeline semantics live in shared code; tool packages receive only the necessary adapter hooks.
2. Identical verification surface. verification-system.js runs the same checks per package, producing comparable pass/fail signals. Source: installer/verification-system.js.
3. Per-package path isolation. path-manager.js prevents one tool's state from leaking into another's on disk. Source: installer/path-manager.js.
4. Uniform reporting. report-template.js formats results the same way regardless of which package failed or passed. Source: installer/report-template.js.

Validation Script

scripts/validate-all-packages.js is the top-level

Design Trade-offs Observed

• Pro: Memory-pipeline redesigns like v2.9.0 ship to all four tools in one change, eliminating per-package drift (release notes).
• Pro: Installer decomposition by *responsibility* (engine / manager / verifier / reporter) rather than by *tool* keeps the four packages from accumulating bespoke installation code paths.
• Con: Any per-tool quirk still has to be expressed as an adapter, and package-manager.js is the bottleneck where that adapter surface is defined.
• Con: Path isolation in path-manager.js means on-disk state is not portable across tools; users switching tooling start cold.

Together these files describe a small, deterministic installer that targets four tool packages through a shared behavioral kernel — the mechanism that lets a release like v2.9.0 propagate uniformly.

Related Pages

Related topics: Agents, Commands, Skills & Workflows

Hot Memory Pipeline (/stash → /friction → /remember)

Purpose and Scope

The Hot Memory Pipeline is the three-stage ingestion flow that turns raw session artifacts into durable, antigen-scoped memory entries. It runs identically across the four tool packages distributed in this repository: claude, opencode, ampcode, and droid. Each package ships its own command wrapper under packages/<tool>/commands/remember/ (or the equivalent command/remember/ layout used by opencode), so a developer working on one surface can reason about the others by symmetry. Source: docs/remember-README.md:1-40

The pipeline exists to solve a specific failure mode observed before v2.9.0: friction events were being written into hot memory verbatim, which poisoned the antigen stream with machine-generated proxies instead of observable user reactions. The redesign re-seeds antigens from what the user actually said, clustered by content and phrase overlap, so downstream memory recall reflects ground-truth friction rather than inferred signals. Source: docs/antigen-gate-prd.md:1-60

Pipeline Stages

Stage 1 — `/stash`

The /stash stage is the entry point. It captures candidate items into a short-lived buffer that the later stages can inspect and filter. Stashing is intentionally permissive: it does not try to judge whether an item is worth remembering. That judgment is deferred to the friction gate so that recall decisions live in one place rather than being smeared across writers and readers. Source: packages/claude/commands/remember.md:1-40

Stage 2 — `/friction`

The /friction stage is the antigen gate. After v2.9.0 it clusters by what the user *said* — content and phrase overlap of observed reactions — rather than by machine proxies such as edit distance, retry counts, or model confidence scores. Each tool package implements this stage in its own friction.js file, but the clustering contract is shared: only user-originated phrases contribute to an antigen. The output is a filtered antigen set that pre-aggregates before the memory write so recall stays scoped. Source: packages/claude/commands/remember/friction.js:1-80 Source: packages/opencode/command/remember/friction.js:1-80

This stage is also where the precision fixes from v2.9.0 land. Prior to the redesign, friction-derived items leaked directly into hot memory; now the gate is the single chokepoint, and any item that lacks user-anchored overlap is rejected before it reaches /remember. Source: docs/antigen-gate-prd.md:40-90

Stage 3 — `/remember`

The /remember stage is the durable writer. It consumes the antigen-gated stream produced by /friction and commits entries to long-term memory. Because the upstream gate has already removed poisoned material, /remember does not need to re-validate provenance — it focuses on persistence, indexing, and surfacing the antigens in subsequent retrieval. The command surface is defined per-package in remember.md and is the only entry point a user invokes directly for the write path. Source: packages/claude/commands/remember.md:40-80

Cross-Package Equivalence

The directory convention differs between opencode (singular command/) and the other three (plural commands/), but the contract is identical. When porting a fix or a precision tweak, the change must be applied to all four friction.js files in lockstep — the v2.9.0 release notes call this out explicitly as a required replication step. Source: docs/antigen-gate-prd.md:90-140

Data Flow

flowchart LR
    A[Session events] --> B["/stash<br/>raw buffer"]
    B --> C["/friction<br/>user-phrase clustering"]
    C --> D["/remember<br/>durable write"]
    D --> E[Hot memory store]

Items enter at session-event granularity, are buffered by /stash, narrowed by /friction against user-observed overlap, and only then promoted to hot memory by /remember. The gate is the only place where precision is enforced, which is why the v2.9.0 redesign concentrates logic there rather than distributing heuristics across writers and readers. Source: docs/remember-README.md:40-90

Operational Notes

• Treat the three commands as a single transaction in intent: do not invoke /remember directly with hand-crafted payloads when reproducing pipeline behavior, because the gate's filtering will not have run.
• The cross-package replication rule means any behavioral change should be verified in all four friction.js implementations before tagging a release; partial rollouts will leave the surfaces divergent.
• The redesign addresses precision, not recall breadth — if an antigen fails to surface, the cause is more likely to be too-strict phrase clustering in /friction than missing data in /stash. Source: docs/remember-README.md:90-130

Related Pages

Related topics: Overview & Installation, Multi-Package Architecture, Hot Memory Pipeline (/stash → /friction → /remember)

Agents, Commands, Skills & Workflows

Overview

The repository distributes a portable sub-agentic manual that ships four parallel tool packages — claude, opencode, ampcode, and droid — each containing the same set of agents, commands, skills, and workflows. The manifest is packages/subagentic-manual.md, which functions as the canonical entry point and glossary for every primitive (agent, command, skill, workflow, friction, remember). Source: packages/subagentic-manual.md

In v2.9.0 the friction antigen-pipeline was redesigned so that the /friction command no longer poisons the hot memory layer with machine proxies; antigens are now seeded from what the user actually said (content/phrase overlap). The same change is applied identically across all four tool packages, keeping the surface area uniform for users who switch between Claude Code, opencode, Ampcode, and Droid.

Primitive Taxonomy

Every tool package mirrors this layout so an authored SKILL.md in packages/claude/skills/tdd-flow/ is duplicated byte-for-byte under packages/opencode/, packages/ampcode/, and packages/droid/. Source: packages/subagentic-manual.md

Agents

Agents are persona files that own state between tool calls. The orchestrator agent routes between sub-agents and skills, while numbered files such as 1-create-prd.md represent ordered phases of a workflow. Each agent file declares its inputs, the skills it may invoke, and the artefacts it must emit. Source: packages/claude/agents/orchestrator.md

1-create-prd.md illustrates the contract pattern: it accepts a brief, consults the relevant skills, and writes a PRD into the working directory before returning control to the orchestrator. Source: packages/claude/agents/1-create-prd.md

Skills

Skills are the leaf-level execution units and live one-directory-deep under packages/<tool>/skills/<skill-name>/SKILL.md. They encode procedure, not persona.

• tdd-flow enforces a red→green→refactor loop and is consulted by any agent that writes or modifies code. Source: packages/claude/skills/tdd-flow/SKILL.md
• test-traps enumerates common test-writing anti-patterns and is invoked by tdd-flow whenever a test is added. Source: packages/claude/skills/test-traps/SKILL.md
• verify-done is a terminal guard-skill: it refuses to mark a workflow complete until the declared exit criteria are demonstrably satisfied. Source: packages/claude/skills/verify-done/SKILL.md

Because skills are pure procedures, they can be reused by any agent across any tool package without behavioural drift.

Commands and the `/friction` → `/remember` Pipeline

Slash-commands sit at the user-facing boundary. The v2.9.0 redesign touched exactly this surface. Previously, /friction produced machine-derived antigens that leaked into /remember's hot memory tier; now antigens are clustered from observed user reactions — phrases the user actually said. The two commands therefore form a directional pipeline:

flowchart LR
    U[User statement] -->|/friction| F[Cluster observed reactions]
    F -->|antigens| R[/remember]
    R --> H[(Hot memory)]
    H --> O[orchestrator context]

The identical logic ships in all four tool packages, so a friction event captured under Claude Code feeds the same memory back to opencode, Ampcode, and Droid. Source: packages/subagentic-manual.md

Workflows

A workflow is not a separate file — it is the runtime composition produced by orchestrator.md when it sequences agents, commands, and skills for a goal. Typical chains follow the numbered agent convention (1-create-prd → 2-... → N-...), each phase exiting only after verify-done confirms its contract. Skills such as tdd-flow and test-traps are pulled in by whichever agent owns the code-touching phase, keeping the workflow deterministic across packages.

Community-Aligned Notes

• The friction redesign in v2.9.0 is explicitly motivated by user feedback that the previous pipeline polluted hot memory with machine-derived noise; the new behaviour clusters by what the user *said*.
• Because the change was propagated identically to claude, opencode, ampcode, and droid, users who switch tools mid-session do not see divergent memory state — a recurring concern in community discussions about cross-tool portability.
• verify-done exists precisely because users reported workflows being marked complete before exit criteria were met; treat it as the authoritative terminator for any chained workflow.

Doramagic Pitfall Log

Found 8 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Identity risk - Identity risk requires verification.

1. Identity risk: Identity risk requires verification

• Severity: medium
• Finding: Project evidence flags a identity risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: identity.distribution | https://github.com/hamr0/liteagents

2. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/hamr0/liteagents

3. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/hamr0/liteagents

4. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/hamr0/liteagents

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/hamr0/liteagents

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/hamr0/liteagents

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/hamr0/liteagents

8. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/hamr0/liteagents

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using liteagents-skill-installer with real data or production workflows.

• Identity risk requires verification - GitHub / issue