SafeFlo

A local and transparent AI agent orchestration platform for Claude Code. MCP server with tools for persistent memory, task planning, and logical agent coordination — no network calls, no hidden install scripts, no modification of files outside the project.

🇷🇺 Read in Russian: README.ru.md

TL;DR

Give Claude Code persistent memory, structured plans, and logical agents. All data lives in ./.safeflow/. Uninstall with a single command. No surprises.

Contents

• What's inside

• Installation

• Using from Claude Code

• Programmatic API

• Uninstall

• Security

• Comparison with similar projects

• Contributing

• License

What's inside

Installation

# Clone the repository — no curl | bash installers.
git clone https://github.com/G1ngercy/SafeFlo.git
cd safeflow

# npm ci strictly follows package-lock.json — no version substitution.
# package.json contains no preinstall/postinstall scripts.
npm ci

# Build and test
npm run build
npm test

To use in your project:

cd /path/to/your/project
node /path/to/safeflow/dist/cli.js init

This creates:

• ./.safeflow/ — local databases and audit log

• ./.claude/commands/safeflow-*.md — slash commands for Claude Code

To register the MCP server with Claude Code:

claude mcp add safeflow -- node /path/to/safeflow/dist/mcp/server.js

Using from Claude Code

Once connected, Claude Code gains these tools:

Memory:

• memory_store(namespace, key, content, metadata?)

• memory_get(namespace, key)

• memory_search(namespace, query, limit?)

• memory_list(namespace, limit?)

• memory_delete(namespace, key)

Planning:

• plan_create(goal)

• plan_add_step(planId, title, description, dependsOn?)

• plan_update_step_status(stepId, status)

• plan_get(planId)

• plan_ready_steps(planId) — steps that are ready to start

• plan_list(limit?)

Agents:

• agent_register(role, task?)

• agent_list(status?)

• agent_update_status(agentId, status)

Audit:

• audit_tail(n?) — last N events from the audit log

And slash commands: /safeflow-plan, /safeflow-memory, /safeflow-agents.

Programmatic API

import {
  MemoryStore,
  TaskPlanner,
  AgentCoordinator,
  AuditLogger,
} from "safeflow";

const audit = new AuditLogger(process.cwd());
const memory = new MemoryStore(process.cwd(), audit);
const planner = new TaskPlanner(process.cwd(), audit);
const coord = new AgentCoordinator(process.cwd(), audit);

memory.store("project.notes", "decision-1", "Use SQLite for memory");

const plan = planner.createPlan("Add authentication");
const step = planner.addStep(plan.id, {
  title: "Design schema",
  description: "users, sessions",
  dependsOn: [],
});

const agent = coord.register("researcher", "Survey auth libraries");

Uninstall

node /path/to/safeflow/dist/cli.js uninstall --yes

This removes:

• ./.safeflow/ — all local databases and audit log

• ./.claude/commands/safeflow-*.md

SafeFlo uses no global paths whatsoever, so there is nothing to clean up outside the project. Genuinely nothing. Verify for yourself: grep -rn "homedir\|os\.home" src/ returns no results.

Security

The full threat model and guarantees are in SECURITY.md. Quick summary:

• No install scripts in package.json (CI checks this automatically).

• No network calls in the code (CI greps for this).

• No modification of files outside the project — all data in ./.safeflow/.

• Parameterized SQL everywhere, Zod validation on every input.

• Protection against path traversal (including ....// bypasses), prototype pollution, SQL injection.

• Transparent MCP descriptions — no hidden directives to the LLM. Audited automatically in CI.

• Complete uninstall with a single command.

• Minimal dependencies — 3 packages with pinned versions (@modelcontextprotocol/sdk, better-sqlite3, zod).

• Provenance — npm packages are published with cryptographic attestation via GitHub Actions.

Vulnerabilities — through private security advisory, not through public issues. See SECURITY.md.

Comparison with similar projects

SafeFlo is designed as a secure alternative to functionally similar projects. The main architectural differences:

Fewer features, more transparency. We don't implement cross-machine "federated" coordination or "enterprise security scan." We do three things (memory, plans, coordination) and do them without surprises.

Contributing

See CONTRIBUTING.md. In short:

• For bugs — issue → fork → PR with a test.

• For features — issue first, then PR.

• For vulnerabilities — private security advisory, not a public issue.

Code of Conduct — CODE_OF_CONDUCT.md.

License

MIT, see LICENSE.