experimental-ash weekly downloads statistics

Ash

Ash is a filesystem-first framework for durable backend agents on Vercel.

You author an agent as a directory on disk. The directory is the contract — markdown for the parts a human should read like a spec, TypeScript for the parts that benefit from real types and runtime behavior.

The framework is called Ash. The published npm package is experimental-ash. The CLI binary is ash.

What Ash Prioritizes

• Markdown-first authoring for instructions and procedures
• TypeScript where typed runtime behavior matters
• Durable message runs and follow-up turns
• Inspectable compiled artifacts under .ash/
• Per-agent sandbox with optional authored overrides
• A stable HTTP protocol with explicit continuationToken and runId contracts
• A runtime model that keeps channels, harnesses, and workflow execution separate

Authored Directory

my-agent/
├── package.json
├── tsconfig.json
└── agent/
    ├── agent.ts           # additive runtime config (model, name, build, compaction, …)
    ├── instructions.md    # always-on instructions prompt
    ├── tools/             # typed executable integrations
    ├── skills/            # optional named procedures the model can load on demand
    ├── hooks/             # lifecycle and stream-event subscribers
    ├── channels/          # message ingress and delivery (HTTP, Slack, …)
    ├── connections/       # external MCP server connections
    ├── sandbox/           # the agent's single sandbox (optional override)
    ├── workspace/         # files seeded into the sandbox on each session
    ├── subagents/         # specialist child agents (reuse `defineAgent`)
    ├── schedules/         # recurring jobs
    └── lib/               # shared authored code imported by other files

Authoring Helpers

Every authored directory has a typed helper. Import each from the matching subpath:

Helper	Subpath	Authored Location
defineAgent(...)	experimental-ash	agent.ts, subagents/<id>/agent.ts
defineInstructions(...)	experimental-ash/instructions	instructions.ts (or instructions.md)
defineTool(...), defineBashTool(...), defineReadFileTool(...), defineWriteFileTool(...), disableTool(...)	experimental-ash/tools	tools/<name>.ts
defineSkill(...), getSkill(...)	experimental-ash/skills	skills/<name>.ts (or skills/<name>.md)
defineHook(...)	experimental-ash/hooks	hooks/<slug>.ts
defineChannel(...), POST, GET	experimental-ash/channels	channels/<name>.ts
ashChannel(...), slackChannel(...), vercelOidc(...)	experimental-ash/channels/ash, /slack, /auth	reused from channels/<name>.ts
defineSandbox(...)	experimental-ash/sandbox	sandbox.ts (or sandbox/sandbox.ts)
defineSchedule(...)	experimental-ash/schedules	schedules/<name>.ts (or schedules/<name>.md)
defineEvalSuite(...)	experimental-ash/evals	evals/<name>.eval.ts

Runtime accessors live on the subpath that owns the concern:

• getSession() — current session, turn, auth, parent lineage (experimental-ash/context)
• getSandbox() — live sandbox handle for the current agent (experimental-ash/sandbox)
• getSkill(identifier) — handle for a named skill visible to the current agent (experimental-ash/skills)
• getContext(key), requireContext(key), hasContext(key), setContext(key), ensureContext(key, factory) — unified context helpers (experimental-ash/context)

The complete API reference, including types and lower-level runtime primitives, is in ./dist/docs/public/advanced/typescript-api.md.

Tiny Example

agent/instructions.md

You are a weather-focused assistant. Be concise, accurate, and explicit when you use a tool.

agent/tools/get_weather.ts

import { defineTool } from "experimental-ash/tools";
import { z } from "zod";

export default defineTool({
  description: "Get the current weather for a city.",
  inputSchema: z.object({
    city: z.string(),
  }),
  async execute(input) {
    return {
      city: input.city,
      condition: "Sunny",
      temperatureF: 72,
    };
  },
});

agent/agent.ts

import { defineAgent } from "experimental-ash";

export default defineAgent({
  model: "openai/gpt-5.4-mini",
});

Quick Start…