@capsuleer/fs

Filesystem module for Capsuleer agents. Gives agents the ability to read, write, search, and navigate the local filesystem — with every operation emitting a structured trace event so Axon has a full audit trail of what was touched.

capsuleer install fs

Built-in — ships with every Capsuleer environment. No configuration required.

API

Reading

// Read an entire file
const content = await fs.read("/project/src/app.ts")

// Check file metadata
const info = await fs.stat("/project/src/app.ts")
// → { size: 4096, mtime: 1710892800000, isFile: true, isDirectory: false }

// Check if a path exists
const exists = await fs.exists("/project/.env")

Writing

// Write a file (creates or overwrites)
await fs.write("/project/out/result.json", JSON.stringify(data, null, 2))

// Create a directory
await fs.mkdir("/project/dist", { recursive: true })

// Move a file
await fs.move("/tmp/draft.ts", "/project/src/final.ts")

// Delete a file or directory (recursive)
await fs.delete("/tmp/scratch")

Searching

// Glob pattern search — returns absolute paths
const files = await fs.find("**/*.ts", { cwd: "/project" })
// → ["/project/src/app.ts", "/project/src/index.ts", ...]

// Regex search across files
const matches = await fs.grep("TODO", "/project/src", { recursive: true })
// → [{ file: "/project/src/app.ts", line: 42, text: "// TODO: fix this", match: "TODO" }]

Directory listing

const entries = await fs.list("/project")
// → [{ name: "src", type: "directory" }, { name: "README.md", type: "file" }]

Observability

Every operation emits a structured JSON event to stdout:

{ "ok": true, "op": "fs.read", "data": { "path": "/project/src/app.ts", "bytes": 4096, "lines": 120 } }
{ "ok": true, "op": "fs.write", "data": { "path": "/project/out/result.json", "bytes": 512, "lines": 18 } }
{ "ok": true, "op": "fs.find", "data": { "pattern": "**/*.ts", "cwd": "/project", "count": 42, "files": [...] } }

Axon collects these as trace events — giving you a complete record of every file the agent read or modified during a session.

Errors emit ok: false with the error message, then re-throw so the agent can handle them.

Policy

Filesystem operations are subject to Capsuleer's policy engine. Control each operation independently:

const capsule = await Capsule({
  policy: {
    fs: {
      read: true,
      write: { deny: ["/etc/**", "~/.ssh/**"] },
      delete: "escalate",   // pause and ask before deleting
      find: true,
      grep: true,
    }
  }
})

See the policy docs for the full rule syntax.