FABER SDK - Development toolkit for AI-assisted workflows
npm install @fractary/faber
faber/
├── cli/ # CLI (@fractary/faber-cli)
│ ├── src/ # TypeScript source
│ ├── dist/ # Compiled output
│ └── package.json # @fractary/faber-cli
├── sdk/
│ ├── js/ # JavaScript/TypeScript SDK
│ │ ├── src/ # TypeScript source
│ │ ├── dist/ # Compiled output
│ │ └── package.json # @fractary/faber (v2.0+)
│ └── py/ # Python SDK
│ ├── faber/ # Python package
│ ├── tests/ # Python tests
│ └── pyproject.toml # faber
├── specs/ # Design specifications
├── docs/ # Documentation
└── package.json # Monorepo root
`
$3
CLI:
`bash
npm run build:cli # Build CLI
npm run test:cli # Test CLI
npm run lint:cli # Lint CLI
`
JavaScript SDK:
`bash
npm run build:js # Build SDK
npm run test:js # Test SDK
npm run lint:js # Lint SDK
`
Python SDK:
`bash
cd sdk/py
pip install -e ".[dev]"
pytest
`
Run all builds:
`bash
From root
npm run build
npm run test
npm run lint
`
---
What is FABER?
FABER enables AI agents to do meaningful work autonomously while knowing exactly when to involve humans.
Unlike simple automation tools that chain API calls, FABER orchestrates AI agents that actually reason about your work. Unlike raw AI frameworks, FABER provides the guardrails enterprises need to deploy with confidence.
`
From issue to PR, autonomously.
`
$3
| Approach | What Happens |
|----------|--------------|
| Deterministic Automation (Zapier, Make) | Works for simple tasks, breaks when reasoning is required |
| Raw AI Agents (LangGraph, AutoGen) | Powerful but unpredictable—enterprises won't adopt |
| AI + Approve Everything | Human becomes the bottleneck, defeats the purpose |
$3
FABER takes a different approach: AI operates autonomously within defined boundaries, escalates intelligently when boundaries are approached.
- Structural Guardrails: The FABER methodology (Frame → Architect → Build → Evaluate → Release) prevents chaos through process
- Boundary Guardrails: Hard limits the AI cannot cross (production deploys, cost thresholds)
- Intelligent Guardrails: AI reasons about its own confidence and risk, deciding when to proceed vs. escalate
The result: 90% autonomous operation, 10% human involvement—focused on decisions that actually matter.
Who is FABER For?
$3
Automate complex development tasks—from understanding an issue to shipping a PR. Focus on interesting problems while AI handles the routine work.
$3
Automated incident response, deployment pipelines, and infrastructure changes with human oversight on critical decisions.
$3
Build AI-powered workflows that your entire organization can use, with the safety and observability enterprises require.
Key Concepts
$3
Every workflow follows five phases:
| Phase | Purpose |
|-------|---------|
| Frame | Understand the problem before acting |
| Architect | Plan the approach before building |
| Build | Implement to specification |
| Evaluate | Validate before shipping |
| Release | Controlled delivery |
$3
Trust is earned, not assumed:
1. Day 1: Conservative—more human checkpoints
2. Week 4: Established patterns—less intervention needed
3. Month 6: Mature—90% autonomous, 10% escalation
$3
| Level | Description |
|-------|-------------|
| dry-run | Preview changes without executing |
| assisted | Pause for user confirmation at each step |
| guarded | Confirm destructive operations only |
| autonomous | Execute within established boundaries |
Installation
`bash
npm install @fractary/faber
`
Quick Start
$3
FABER uses a two-phase approach: plan (CLI) + execute (Claude Code):
`bash
1. Plan workflow (creates plan, branch, worktree)
fractary-faber workflow-plan --work-id 258
2. Execute workflow (in Claude Code session)
cd ~/.claude-worktrees/fractary-myproject-258
claude
/fractary-faber:workflow-run 258
`
Batch Planning:
`bash
Plan multiple workflows at once
fractary-faber workflow-plan --work-id 258,259,260
Or search by labels
fractary-faber workflow-plan --work-label "workflow:etl,status:approved"
`
Benefits:
- ✅ Plan 10+ workflows in one command
- ✅ Each workflow runs in isolated worktree
- ✅ Parallel execution across multiple Claude sessions
- ✅ Claude focuses only on execution (no planning confusion)
$3
`typescript
import { FaberWorkflow } from '@fractary/faber';
// Run a complete FABER workflow
const workflow = new FaberWorkflow();
const result = await workflow.run({
workId: '123',
autonomy: 'assisted'
});
`
$3
`bash
Check workflow run status
fractary-faber run-inspect --work-id 258
Manage work items
fractary-faber work issue fetch 123
fractary-faber work comment create 123 --body "Starting"
Repository operations
fractary-faber repo branch create feat/fix-123
fractary-faber repo pr create "Fix issue" --body "Resolves #123"
`
See CLI README for comprehensive documentation.
SDK Modules
The FABER SDK provides modular primitives for building AI-powered workflows:
| Module | Purpose | Import |
|--------|---------|--------|
| Work | Issue tracking (GitHub, Jira, Linear) | @fractary/faber/work |
| Repo | Git & PRs (GitHub, GitLab, Bitbucket) | @fractary/faber/repo |
| Spec | Specification management | @fractary/faber/spec |
| State | Workflow persistence & checkpoints | @fractary/faber/state |
| Logs | Session capture & audit trails | @fractary/faber/logs |
| Storage | Artifact storage with Codex integration | @fractary/faber/storage |
| Workflow | Full FABER orchestration | @fractary/faber/workflow |
$3
`typescript
import { WorkManager } from '@fractary/faber/work';
const work = new WorkManager();
const issue = await work.fetchIssue(123);
await work.createComment(123, 'Starting implementation');
const workType = await work.classifyWorkType(issue); // 'feature' | 'bug' | 'chore'
`
$3
`typescript
import { RepoManager } from '@fractary/faber/repo';
const repo = new RepoManager();
await repo.createBranch('feature/add-export', { base: 'main' });
await repo.createPR({ title: 'Add export feature', head: 'feature/add-export' });
await repo.commit({ message: 'Add feature', type: 'feat' });
`
$3
`typescript
import { FaberWorkflow } from '@fractary/faber/workflow';
const faber = new FaberWorkflow({
config: {
autonomy: 'guarded',
phases: {
frame: { enabled: true },
architect: { enabled: true, refineSpec: true },
build: { enabled: true },
evaluate: { enabled: true, maxRetries: 3 },
release: { enabled: true, requestReviews: true },
},
},
});
// Event handling
faber.addEventListener((event, data) => {
console.log(${event}:, data);
});
// Run workflow
const result = await faber.run({ workId: '123' });
`
CLI Commands
For comprehensive CLI documentation, see @fractary/faber-cli.
Quick reference:
`bash
Workflow
fractary-faber configure # Initialize project
fractary-faber workflow-run --work-id # Run workflow
fractary-faber run-inspect --work-id # Check status
fractary-faber workflow-resume # Resume workflow
Work tracking
fractary-faber work issue fetch
fractary-faber work issue create --title "Feature"
fractary-faber work comment create --body "Update"
fractary-faber work label add --label "bug"
Repository
fractary-faber repo branch create
fractary-faber repo pr create --title "Title"
fractary-faber repo commit "feat: message"
fractary-faber repo tag create v1.0.0
Logs
fractary-faber logs capture
fractary-faber logs read
`
$3
Plan workflows for prioritized backlogs:
`bash
Plan top 5 priorities
fractary-faber workflow-plan --work-label "status:backlog" --order-by priority --limit 5
Plan most recently updated issues
fractary-faber workflow-plan --work-label "status:backlog" --order-by updated --limit 10
Plan oldest issues first (FIFO)
fractary-faber workflow-plan --work-label "status:backlog" --order-by created --order-direction asc --limit 3
`
Key features:
- Priority ordering: Use priority-1 through priority-10 labels (lower = higher priority, recommend 1-4)
- Date ordering: Sort by created or updated date
- Limit results: Plan manageable batches with --limit
- Flexible filtering: Combine with any label filters
See Backlog Management Guide for complete documentation.
Configuration
Configuration is stored in .fractary/config.yaml:
`yaml
.fractary/config.yaml
github:
organization: your-org
project: your-repo
faber:
workflows:
path: .fractary/faber/workflows
default: default
autonomy: guarded
runs:
path: .fractary/faber/runs
`
Platform Support
| Platform | Work Tracking | Repository |
|----------|--------------|------------|
| GitHub | Full | Full |
| Jira | Planned | - |
| Linear | Planned | - |
| GitLab | - | Planned |
| Bitbucket | - | Planned |
Documentation
$3
- Getting Started Guide - Installation and first steps
- Core Concepts - FABER methodology and architecture
- Guardrails System - Three layers of safety
$3
- API Reference - Complete SDK API documentation (TypeScript & Python)
- CLI Integration - CLI usage patterns and integration
- Configuration - Complete configuration reference
- Troubleshooting - Common issues and solutions
$3
- Code Examples - Runnable TypeScript and Python examples
- Simple Workflow - Basic workflow execution
- Work Tracking - Issue and PR automation
- Repository Automation - Branch and PR management
- And more...
$3
- CLI Reference - Command-line interface
- MCP Server - Model Context Protocol integration
- Python SDK - Python SDK guide
$3
- SDK Architecture - Technical architecture overview
- LangGraph Integration - Graph-based workflow orchestration
- Intelligent Guardrails - Confidence-based autonomy system
- Multi-Workflow Orchestration | DAC foundation
$3
- FABER Vision - Mission, philosophy, and strategic positioning
Type Exports
All types are exported for TypeScript consumers:
`typescript
import type {
// Workflow
WorkflowConfig, WorkflowResult, PhaseResult, FaberPhase, AutonomyLevel,
// Work
Issue, IssueCreateOptions, Comment, Label, WorkType,
// Repo
PullRequest, PRCreateOptions, Branch, BranchCreateOptions,
// Spec
Specification, SpecTemplate, ValidationResult,
} from '@fractary/faber';
`
Domain-Specific Plugins
FABER's core framework can be extended with domain-specific plugins:
| Plugin | Description | Install |
|--------|-------------|---------|
| faber-software | Software development agents | forge install @fractary/faber-software |
| faber-cloud | Cloud infrastructure automation | forge install @fractary/faber-cloud |
| faber-content | Content creation workflows | forge install @fractary/faber-content` |