YATFA Agent (Yet Another Tool For Agents)

Run YATFA agents in any Docker container with Ruby.

Quick Start

The easiest way to get started is with the interactive setup wizard:

npx yatfa setup

The wizard will guide you through:

1. YATFA Platform URL - Your YATFA instance
2. Agent API Keys - From the YATFA web UI
3. Git Configuration - Identity for commits
4. GitHub Authentication - Token or App credentials
5. Environment Variables (optional) - API keys, secrets

The wizard validates everything before creating your configuration file.

Manual Setup

If you prefer to configure manually, create Dockerfile.sandbox in your project root (copy your existing Dockerfile). Read INSTALLATION.md for detailed guide.

Configuration (yatfa.env.rb)

Agents are configured via a yatfa.env.rb file in your project root. This Ruby file allows you to define configuration and secrets (using heredocs).

Do not commit yatfa.env.rb to git! Add it to your .gitignore.

Pro tip: Use npx yatfa setup to generate this file interactively with validation.

Example yatfa.env.rb:

{
  yatfa_url: "https://yatfa.ai",  # Platform URL

  # Git Identity
  git: {
    user_name: "YATFA Agent",
    user_email: "[email protected]"
  },

  # GitHub Auth (Optional)
  # GitHub authentication is now handled by the Rails backend
  # The backend uses its own GitHub App to generate tokens for agents
  # You can remove the 'github' section entirely, or use GH_TOKEN as fallback
  github: {
    token: "ghp_..." # Optional: for development/testing only
  },

  # Agent Specific Config
  agents: {
    worker: {
      mcp_api_key: "...",
      container_name: "yatfa-worker"
    },
    planner: {
      mcp_api_key: "...",
      container_name: "yatfa-planner"
    }
  },

  # Environment Variables Injection
  # Simple strings or Heredocs supported
  dot_env: <<~ENV
    PORT=3200
    DB_HOST=localhost
    SECRET_KEY_BASE=very_secret
  ENV
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | AGENT_TYPE | ✅ | worker, planner, reviewer, or researcher | | YATFA_API_KEY | ✅ | MCP API key (get from YATFA dashboard) | | YATFA_URL | | Yatfa platform URL (defaults to https://yatfa.com; YATFA_API_URL & YATFA_WS_URL are derived from this) | | GH_TOKEN | | GitHub token for git operations (fallback; backend token auth is preferred) |

Agent Types

| Type | Mode | Purpose | |------|------|---------| | planner | Interactive | Chat with human, create tickets | | worker | Autonomous | Implement tickets, create PRs | | reviewer | Autonomous | Review PRs, approve/reject | | researcher | Autonomous | Analyze codebase, document findings |

Commands

Setup

npx yatfa setup

Launches interactive setup wizard to configure yatfa.env.rb.

Check Version

npx yatfa version
npx yatfa -v
npx yatfa --version

Run Agents

When you run an agent, the CLI automatically:

1. Checks if the agent is already running - prompts to Attach, Restart, or Cancel
2. Starts the agent - creates the Docker container
3. Prompts to attach - after starting, asks if you want to attach to the session

npx yatfa worker
npx yatfa planner
npx yatfa reviewer
npx yatfa researcher

Non-interactive Mode (for CI/scripts)

# Run without prompts
npx yatfa worker --no-prompt
# or
YATFA_NO_PROMPT=1 npx yatfa worker

Attach to Running Agents (deprecated)

The attach command still works but is deprecated. Running npx yatfa <agent-type> now prompts to attach automatically.

npx yatfa attach worker  # Deprecated - use 'npx yatfa worker' instead

List Agent Status (ps)

See which agent containers are on your machine and what each is doing server-side (idle/busy, current ticket) — like a Unix ps for your local fleet.

npx yatfa ps

Example output:

NAME                      STATUS         AGENT      AVAIL   WORK
yatfa-autonomous-worker   Up 3 hours     worker     busy    YATFA-3315
yatfa-autonomous-reviewer Up 12 mins     reviewer   idle    —
yatfa-planner             Exited (0)     planner    —       —

Rows are local yatfa-managed Docker containers, enriched with server status fetched from your project and merged on agent type. AVAIL is idle/busy/offline (— for agent types that don't track availability, e.g. planner, or when the server status is unavailable). WORK is the agent's current in-progress ticket.

• Requires an API key in yatfa.env.rb (run npx yatfa setup first).
• If the server is unreachable, the local listing is still shown with a warning.
• --json emits machine-readable rows containing both local and remote fields.

npx yatfa ps --json

List Running Agents

npx yatfa ps      # detailed table with server-side status
npx yatfa list    # alias for 'ps'

Lifecycle Control (existing containers)

Control already-created agent containers on this host — no server round-trip, these act on Docker directly. <target> is an agent type (e.g. worker — acts on ALL instances of that type) or a literal container name (a single instance).

npx yatfa stop <target>       # stop the matching container(s)
npx yatfa start <target>      # start the matching stopped container(s)
npx yatfa restart <target>    # restart the matching container(s)
npx yatfa remove <target>     # stop + remove (prompts unless --no-prompt)
npx yatfa stop-all            # stop every yatfa-managed container

• Unknown name/type exits non-zero with a clear one-line error (never a stack trace).
• remove and stop-all prompt for confirmation in interactive mode; skipped with --no-prompt (or YATFA_NO_PROMPT=1, or when stdin is not a TTY).

What the Script Does

1. Validates requirements - Checks for Ruby, Node, tmux, git, claude CLI
2. Creates .mcp.json - Configures MCP tools for the agent type
3. Creates CLAUDE.md - Role-specific instructions Claude sees on startup
4. Sets up GitHub auth - Requests tokens from Rails backend for git operations
5. Downloads agent-bridge - Binary that connects to YATFA via WebSocket
6. Starts tmux session - With status bar showing connection state

Note: GitHub credentials are now managed centrally in the Rails backend. Agents request GitHub tokens via the API endpoint /api/v1/github/token using their MCP API key. This is more secure than storing private keys in each agent's configuration.

Knowledge Injection System

YATFA agents can automatically receive project-specific knowledge through the Knowledge Article system. This enables agents to learn project-specific patterns, conventions, and context without manual configuration.

How It Works

The knowledge injection system uses Claude hooks to fetch relevant knowledge articles from the Rails API and inject them into the agent's context at key moments:

1. Session Start Hook (sessionstart-input.sh) - Injects agent-specific state knowledge when an agent session starts
2. Skill Hooks - Injects skill-specific hints when particular skills are invoked (e.g., git-workflow, ticket-management)

Knowledge Categories

Knowledge articles are organized by purpose, not content type:

| Category | Purpose | Example | |----------|---------|---------| | agent_state_worker | Worker agent's evolving context | Git patterns, testing conventions | | agent_state_planner | Planner agent's context | Ticket creation patterns | | agent_state_reviewer | Reviewer agent's context | Code review standards | | agent_state_researcher | Researcher agent's context | Analysis patterns | | skill_hint_git-workflow | Git workflow guidance | Branch naming, commit conventions | | skill_hint_ticket-management | Ticket management guidance | Ticket creation workflows | | project_knowledge | General documentation | Architecture docs, troubleshooting |

Setup Requirements

The knowledge injection system requires these environment variables:

YATFA_URL=https://yatfa.example.com
YATFA_API_KEY=your_api_key_here
AGENT_TYPE=worker

Note: YATFA_URL is optional and defaults to https://yatfa.com (the hosted deployment works with zero URL configuration; self-hosted installs set it to their server). YATFA_API_URL (/api/v1) and YATFA_WS_URL (/cable, scheme-adjusted) are always derived from it — you never need to set them. The git credential helper derives YATFA_API_URL itself, so even a bare docker exec shell with no other env can authenticate. Project is automatically determined by the API key.

Agent Self-Update

Agents can modify their own knowledge via MCP tools:

# Agent updates its state
update_knowledge_article(
  article_id: 42,
  content: "Updated pattern based on recent work...",
  category: "agent_state_worker"
)

Changes take effect on the next /new command or session restart.

Managing Knowledge Articles

Knowledge articles are managed through the Rails API or MCP tools:

• Create: store_knowledge_article via MCP
• Search: search_knowledge_articles via MCP
• Update: Edit articles via Rails dashboard or MCP
• Categorize: Assign to appropriate category for automatic injection

Example Workflow

1. Human creates a knowledge article:

   # Via MCP or Rails API
   create_article(
     title: "Worker Git Conventions",
     category: "agent_state_worker",
     content: "Always use feature/ticket-id-description format..."
   )

2. Agent session starts:

   # sessionstart-input.sh runs automatically
   # Fetches agent_state_worker articles
   # Injects them into Claude's context

3. Agent has context:

   # Worker sees this at session start:
   ## Knowledge: Worker Git Conventions
   Always use feature/ticket-id-description format...

Hook Files

Hook scripts are located in /hooks/:

• sessionstart-input.sh - Runs when Claude session starts
• skill-hooks/*.sh - Runs when specific skills are loaded

See hook files for implementation details and customization options.

Attaching to Running Agent

After starting an agent, the CLI will prompt you to attach. You can also attach directly:

docker exec -it <container> tmux attach -t agent

Press Ctrl+B then D to detach.

License

MIT