weft

Scheduled tasks (Daily, Weekly, or Cron) follow a two-stage execution model to ensure safety:

1. Trigger: A Durable Object alarm triggers the scheduled time.
2. Read-Only Parent Agent: The parent agent runs with read-only tool access. It cannot send emails, create PRs, or modify documents. Its purpose is to analyze data (e.g., scanning an inbox) and call create_task to fork child tasks.
3. Full-Access Child Tasks: Each child task receives its own agent context with full tool access. These tasks run until they complete or require human approval for state-mutating actions.

This architecture allows agents to perform overnight analysis while ensuring that no actual changes (like sending an email) occur without human review.

Each Weft board has its own configuration accessible via the Settings menu. Settings are organized into two main areas:

• Credentials:
  • Anthropic API key: Required for agents to function. This is stored per-board.
  • OAuth accounts: Connect your Google and GitHub accounts for integration access.
• Integrations:
  • Enable built-in tools like Gmail, Docs, Sheets, or GitHub.
  • Add remote MCP servers to bring in custom tools via the Model Context Protocol.

To use Gmail, Docs, or Sheets integrations, you must configure a Google OAuth client:

1. In the Google Cloud Console, enable the Gmail API, Google Docs API, and Google Sheets API.
2. Configure the OAuth consent screen (External mode is sufficient; add yourself as a test user).
3. Create OAuth client ID credentials for a Web application.
4. Authorized JavaScript origins:
   • Dev: http://localhost:5174
   • Prod: https://weft.<your-subdomain>.workers.dev
5. Authorized redirect URIs:
   • Dev: http://localhost:5174/google/callback
   • Prod: https://weft.<your-subdomain>.workers.dev/google/callback
6. Add the resulting GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET to your .env file.

To deploy Weft to your Cloudflare account, you must first set your required secrets using Wrangler, then run the production deployment command.

Required Secrets:

• ENCRYPTION_KEY: Encrypts stored credentials. Generate with openssl rand -base64 32.
• GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET: For Google integrations.
• GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET: For GitHub integration.

Deployment Commands:

npx wrangler secret put ENCRYPTION_KEY --env production
npx wrangler secret put GOOGLE_CLIENT_ID --env production
npx wrangler secret put GOOGLE_CLIENT_SECRET --env production
npx wrangler secret put GITHUB_CLIENT_ID --env production
npx wrangler secret put GITHUB_CLIENT_SECRET --env production

npm run deploy:prod

To set up Weft on your local machine, follow these steps:

1. Clone and install dependencies:

   git clone https://github.com/jonesphillip/weft.git
   cd weft
   npm install

2. Configure environment variables: Copy the example file to .env:

   cp .env.example .env

   Edit .env to include your ENCRYPTION_KEY (generated via openssl rand -base64 32) and any OAuth credentials for Google or GitHub.
3. Start the development server:

   npm run dev

   This launches the Vite frontend and Wrangler worker. Access the application at http://localhost:5174.

To use GitHub integrations, configure a GitHub OAuth App:

1. Go to GitHub Developer Settings and click New OAuth App.
2. Set the Homepage URL to your Weft deployment URL.
3. Set the Authorization callback URL:
   • Dev: http://localhost:5174/github/callback
   • Prod: https://weft.<your-subdomain>.workers.dev/github/callback
4. Copy the Client ID and Client Secret to your .env file.

Weft uses a registry-driven architecture for integrations. To add a new built-in integration, follow these steps:

1. Create the MCP server: Implement the server logic within the worker/ directory (e.g., worker/google/GmailMCP.ts).
2. Register the server: Add the new server to the registry in worker/mcp/AccountMCPRegistry.ts.
3. Handle OAuth (if required): If the integration requires OAuth, add the necessary handler in worker/handlers/oauth.ts.

The registry handles tool schemas, OAuth configuration, and workflow guidance, meaning you do not need to modify the core agent workflow logic.

The core data model of Weft revolves around a hierarchical structure:

1. User: Represents an authenticated user with an id, email, and an optional logoutUrl.
2. Board: The top-level container for organization. It contains columns, a name, an ownerId, and optional toolConfig for agentic capabilities.
3. Column: A vertical grouping within a Board used to organize tasks. It has a position for ordering.
4. Task: The fundamental unit of work. Tasks belong to a columnId and boardId. They include title, description, priority ('low' | 'medium' | 'high' | 'critical'), and position. Tasks can also have a parentTaskId for nesting and a scheduleConfig for automation.

Boards can be extended with agentic capabilities via BoardToolConfig. This allows the board to interact with external systems using defined tools and credentials.

ToolDefinition: Defines a specific capability.

• type: Can be 'mcp' (Model Context Protocol), 'api', 'filesystem', or 'browser'.
• config: Contains endpoint, permissions, and scope.

CredentialRef: References encrypted credentials stored by the system.

SandboxSettings: Controls the execution environment for tools, allowing limits on memoryLimitMb, timeoutMs, and allowedDomains.

export interface BoardToolConfig {
  tools: ToolDefinition[];
  credentials: CredentialRef[];
  sandboxConfig?: SandboxSettings;
}

A WorkflowPlan represents a sequence of steps (an agentic plan) to achieve a goal.

Lifecycle (WorkflowPlanStatus): 'planning' -> 'draft' -> 'approved' -> 'executing' -> 'checkpoint' -> 'completed' | 'failed'

Workflow Steps: Each plan consists of WorkflowSteps. Steps can be of type:

• tool_call: Invoking a specific tool.
• checkpoint: A pause point for human intervention or state saving.
• internal: System-level operations.
• agent: An LLM-driven turn.
• tool: General tool usage.

Results and Artifacts: Successful workflows produce WorkflowArtifacts, which can be 'google_doc', 'google_sheet', 'gmail_message', 'github_pr', 'file', or 'other'. The WorkflowResult captures the success status and any generated artifacts or step results.