DOCSEARCHbyAlgolia
Submit Docs

beans

repository·main·Indexed 21 days ago

https://github.com/hmans/beans

An issue tracker that stores tasks as Markdown files within a project's .beans directory. It provides a CLI and TUI for humans, and a GraphQL query engine with prompt instructions for coding agents to track progress, create bugs, and maintain project memory.

Tokens
23.4K
Snippets
103
Records
116
Agent score
74%

What's inside beans

  1. Build and preview for production

    main

    To prepare your application for production, run the build command. Once built, you can use the preview command to verify the production build locally. Note that for actual deployment, you may need to install a SvelteKit adapter specific to your target environment.

    # Create a production version of your app
npm run build

# Preview the production build
npm run preview

  2. Install the beans CLI

    main

    You can install the beans CLI tool using Homebrew or Go. This tool is required to manage tasks and initialize Beans in your project.

    # Via Homebrew
brew install hmans/beans/beans

# Via Go
go install github.com/hmans/beans@latest

  3. Configure OpenCode with the Beans plugin

    main
    To integrate Beans with OpenCode, copy the plugin file from .opencode/plugin/beans-prime.ts to your project's .opencode/plugin/ directory. For global availability across all projects, copy it to ~/.opencode/plugin/ instead.

  4. Configure your coding agent for Beans

    main

    To enable your coding agent to interact with Beans, you must provide it with instructions. The most basic method is to add the following instruction to your agent's configuration file (e.g., AGENTS.md, CLAUDE.md, or equivalent):

    **IMPORTANT**: before you do anything else, run the beans prime command and heed its output.

    **IMPORTANT**: before you do anything else, run the `beans prime` command and heed its output.

  5. Start the development server

    main

    After creating your project and installing dependencies (using npm install, pnpm install, or yarn), you can start the local development server. Use the --open flag to automatically open the application in a new browser tab.

    npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open

  6. Create a new Svelte project with sv

    main

    Use the sv CLI (powered by sveltejs/cli) to scaffold a new Svelte project. You can either initialize the project in the current directory or specify a new directory name.

    # create a new project in the current directory
npx sv create

# create a new project in my-app
npx sv create my-app

  7. Initialize Beans in your project

    main
    To start using Beans in an existing project, run beans init from your project's root directory. This creates a .beans/ directory for storing task data as Markdown files and a .beans.yml configuration file. Both should be tracked in your version control system.
    beans init

  8. Use the beans CLI

    main

    The beans CLI is a file-based issue tracker designed for AI-first workflows. It stores issues as markdown files, allowing you to track work alongside your code. To use the CLI, you must have a .beans directory initialized in your project or specified via configuration.

    beans [command] [flags]

  9. Understand Agent Session states and modes

    main

    An AgentSession represents an active AI agent working within a specific worktree.

    Modes:

    • Act Mode (actMode): The agent is fully autonomous and does not require permission prompts for tool calls.
    • Plan Mode (planMode): The agent is in read-only mode; it can explore and analyze the codebase but cannot perform edits.

    Statuses (AgentSessionStatus):

    • IDLE: No active task.
    • RUNNING: The agent is currently processing.
    • ERROR: The session encountered a failure.

  10. Understand the Bean data model

    main

    A Bean is the core unit of work in the system. Key properties include:

    • id: A unique NanoID.
    • status: Current state (draft, todo, in-progress, completed, scrapped).
    • type: Category (milestone, epic, bug, feature, task).
    • priority: Importance (critical, high, normal, low, deferred).
    • blockedBy / blocking: Relationships defining dependencies.
    • isDirty: Indicates if the bean has unsaved runtime changes.
    • etag: Used for optimistic concurrency control during updates.

  11. Configure Claude Code hooks for Beans

    main

    For Claude Code, you can automate the initialization process by adding hooks to your .claude/settings.json file. This ensures the agent runs beans prime at the start of a session and before compaction.

    {
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "beans prime" }] }
    ],
    "PreCompact": [
      { "hooks": [{ "type": "command", "command": "beans prime" }] }
    ]
  }
}

  12. How backlog drag-and-drop works

    main

    The backlogDrag state manages drag-and-drop operations for recursive Bean items in the backlog view. It uses a single source of truth to track which bean is being dragged and where the drop target is located.

    Card Hover Zones

    When hovering over a card, the system determines the dropMode based on the vertical position relative to the card's height:

    • Top 25%: Sets dropMode to 'reorder' to place the item above the hovered bean.
    • Middle 50%: Sets dropMode to 'reparent' to make the hovered bean the new parent of the dragged item.
    • Bottom 25%: Sets dropMode to 'reorder' to place the item below the hovered bean.

    Drop Modes

    • reorder: Moves a bean to a specific index within a parent group. Controlled by dropTargetParent and dropIndex.
    • reparent: Changes the parent of a bean to a different bean. Controlled by reparentTargetId.

    Visual Indicators

    The state provides helper methods to determine when to show UI feedback:

    • showIndicator(...): Returns true if a reorder line should appear at a specific index.
    • showEndIndicator(...): Returns true if a reorder line should appear at the end of a list.
    • isReparentTarget(beanId): Returns true if the hovered bean is currently targeted for reparenting.
    // Example of checking for visual indicators in a Svelte component
{#if backlogDrag.showIndicator(bean.parentId, index, bean.id, bean.status)}
  <div class="drop-indicator"></div>
{/if}