Moss

A terminal agent and TypeScript harness for coding, research, automation, and robotics.

Built by D-Robotics (地瓜机器人)

English · 简体中文

Moss works in a repository like a coding agent, researches current information through multiple web paths, and connects to robot development boards over persistent SSH. The same runtime can also be embedded in a TypeScript app, or driven over the ACP wire protocol by an IDE.

Requires Node.js ≥ 22.16. The published CLI ships a ready-to-use D-Robotics model — no personal API key needed for the first run.

npm install -g @rdk-moss/agent@latest
cd your-project
moss

moss                                  # interactive TUI
moss "review the current diff"        # one-shot task
moss resume --last                    # resume the latest session
moss doctor                           # diagnose the local setup
moss --help --all                     # complete CLI reference

• Controllable while running — steer the active task, queue follow-ups, ask an isolated BTW question, inspect details, or stop safely.
• Built for long work — named sessions, persistent goals, context pruning + compaction, resumable state, an optional autonomous loop.
• Safe by default — the balanced profile supports normal dev while asking before sensitive actions; unrestricted execution is explicit.
• Evidence-oriented research — search, direct fetch, RSS discovery, browser reading, and parallel source collection instead of trusting one result.
• First-class robotics — persistent device sessions, environment discovery, board diagnostics, USB/MIPI cameras, ROS 1/2 tools.
• A real harness, not only a CLI — providers, sessions, tools, hooks, approvals, usage events, async tasks, knowledge, skills, MCP, host adapters, and an ACP stdio server are public contracts.

Topic-focused user guides live in docs/user-guide/:

• Getting started · Slash commands · Configuration
• Sessions · Background tasks · Doctor
• Skills · MCP servers · Plan mode · Sandbox & permissions

For host authors + contributors: docs/ (architecture, host-adapter contract, design), packages/moss-agent/EXTENDING.md, packages/moss-agent/API.md.

npm install @rdk-moss/agent @rdk-moss/core
npx create-moss-app my-agent   # scaffold a new host

import { InMemorySessionStore, MossAgent, OpenAILLMProvider, registerBuiltinTools } from '@rdk-moss/agent';

const agent = new MossAgent({
  llmProvider: new OpenAILLMProvider({ apiKey: process.env.MY_MODEL_API_KEY!, baseUrl: 'https://your-provider.example/v1', defaultModel: 'your-model' }),
  sessionStore: new InMemorySessionStore(),
  model: 'your-model',
  workspaceDir: process.cwd(),
  hooks: { onBeforeToolExec: async ({ tool }) => tool.metadata?.sideEffectClass === 'readonly' ? { approved: true } : { approved: false, reason: 'Host approval required' } },
});
registerBuiltinTools(agent);

for await (const event of agent.streamChat('session-1', 'Check project health')) {
  if (event.type === 'text_delta') process.stdout.write(event.delta);
}
await agent.close();

The public runtime: provider, session-store, streaming event + ChatResult contracts; built-in + custom tools, approvals, hooks, guardrails, structured output; context budgets, pruning, compaction, prompt-cache + usage telemetry; knowledge, memory, skills, capability packs, MCP, platform extensions; async tasks, device SSH, robotics helpers, diagnostics. See EXTENDING.md + API.md.

The default profile is balanced (normal dev with approval for sensitive actions); readonly and autonomous are the bounds. Safety-sensitive fields (approvalPolicy, safetyMode, trustedTools, deniedTools) are user-over-project — a cloned repo cannot lower your safety stance.

moss setup          # guided: provider, base URL, API key, model
moss config --help  # all config keys + sources
moss doctor         # health-check the resolved config

See Configuration + Sandbox & permissions.

packages/moss/              provider-neutral contracts + prompt policy
packages/moss-agent/        runtime, loop, context, tools, TUI, CLI, robotics, ACP
packages/create-moss-app/  embeddable agent project scaffolding
docs/                      design notes, architecture, benchmarks, user guide
scripts/                   verification, release, benchmark, smoke tooling

The core loop stays provider-neutral. Coding, research, robotics, and host-specific behavior compose through tools, prompt layers, capability packs, skills, knowledge modules, and adapters — not one monolithic mode.

git clone https://github.com/D-Robotics/moss.git
cd moss
npm install
npm run verify            # boundaries + hygiene + benchmark + build + typecheck + lint + test
npm run smoke:moss-cli   # pack workspaces, install, verify the CLI + PTY startup

Contribution guidance in CONTRIBUTING.md. Security issues: packages/moss-agent/SECURITY.md.

MIT