jb-beans

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

beans - Flat-File Issue Tracker

beans - 纯文件型问题跟踪工具

A lightweight, flat-file issue tracker for humans and AI coding agents. Stores issues as markdown files in

.beans/

directory alongside your code.

IMPORTANT: before you do anything else, run the

beans prime

command and heed its output, but also heed the exceptions at "When to create beans".

一款面向人类和AI编码Agent的轻量级纯文件型问题跟踪工具。将问题以Markdown文件形式存储在代码旁的

.beans/

目录中。

重要提示：在进行任何操作之前，请先运行

beans prime

命令并留意其输出，同时也要注意“何时创建beans”部分的例外情况。

Why beans?

为什么选择beans？

Simple — No database, no server, just markdown files
AI-friendly — Designed for AI coding agents
Git-friendly — Lives alongside your code in
```
.beans/
```
Portable — Works with any editor/IDE

简单易用 — 无需数据库，无需服务器，仅使用Markdown文件
AI友好 — 专为AI编码Agent设计
Git友好 — 与代码一同存放在
```
.beans/
```
目录中
便携性强 — 可与任何编辑器/IDE配合使用

Installation

安装

bash

undefined

bash

undefined

Via Homebrew

brew install hmans/beans/beans

Via Go

go install github.com/hmans/beans@latest

undefined

go install github.com/hmans/beans@latest

undefined

Setup

初始化

bash

undefined

bash

undefined

Initialize beans in a project

在项目中初始化beans

beans init

Verify setup and integrity

验证设置和完整性

beans check

undefined

beans check

undefined

Core Commands

核心命令

Create Beans

创建Beans

bash

beans create "Implement user login"

bash

beans create "Implement user login"

Creates new bean with auto-generated ID

创建带有自动生成ID的新bean

beans create "Fix auth bug" --tag bug --tag urgent --type bug

Creates bean with tags and type

创建带有标签和类型的bean

beans create "Refactor API" --priority high --status todo

Creates bean with priority and status

创建带有优先级和状态的bean

beans create "Add onboarding flow" --body "Scope: screens + copy"

Adds body content

添加正文内容

undefined

undefined

List Beans

列出Beans

bash

beans list                    # List all beans
beans list --tag urgent       # Filter by tag
beans list --status todo      # Filter by status
beans list --type feature     # Filter by type
beans list --search "login"   # Full-text search (Bleve query syntax)

bash

beans list                    # 列出所有beans
beans list --tag urgent       # 按标签筛选
beans list --status todo      # 按状态筛选
beans list --type feature     # 按类型筛选
beans list --search "login"   # 全文搜索（使用Bleve查询语法）

Update Beans

更新Beans

bash

beans update <id> --status in-progress
beans update <id> --title "New title"
beans update <id> --tag bug --remove-tag urgent
beans update <id> --priority high --type feature
beans update <id> --body "Updated scope notes"

bash

beans update <id> --status in-progress
beans update <id> --title "New title"
beans update <id> --tag bug --remove-tag urgent
beans update <id> --priority high --type feature
beans update <id> --body "Updated scope notes"

Show Bean Details

查看Bean详情

bash

beans show <id>               # Show full bean details
beans show <id> --body-only   # Only body content
beans show <id> --raw         # Raw markdown (no styling)

bash

beans show <id>               # 查看完整的bean详情
beans show <id> --body-only   # 仅查看正文内容
beans show <id> --raw         # 查看原始Markdown（无样式）

Delete and Archive

删除与归档

bash

beans delete <id>             # Delete bean (prompts unless --force)
beans archive                 # Delete completed/scrapped beans

bash

beans delete <id>             # 删除bean（除非使用--force，否则会提示确认）
beans archive                 # 删除已完成/废弃的beans

Integrity and TUI

完整性检查与终端交互界面（TUI）

bash

beans check                   # Validate config and bean graph
beans check --fix             # Auto-fix broken links/self-references
beans tui                     # Interactive terminal UI

bash

beans check                   # 验证配置和bean关联图
beans check --fix             # 自动修复损坏的链接/自引用
beans tui                     # 交互式终端UI

Roadmap and GraphQL

路线图与GraphQL

bash

beans roadmap                 # Markdown roadmap from milestones/epics
beans graphql '{ beans { id title status } }'

bash

beans roadmap                 # 根据里程碑/史诗生成Markdown格式的路线图
beans graphql '{ beans { id title status } }'

beans prime

The

beans prime

command outputs project context for AI agents:

bash

beans prime

beans prime

命令为AI Agent输出项目上下文信息：

bash

beans prime

Outputs current beans, tags, and status for AI context

输出当前beans、标签和状态，作为AI的上下文信息

undefined

undefined

Integration with OpenCode

与OpenCode集成

Copy this plugin to your OpenCode config:

typescript

// ~/.opencode/plugin/beans-prime.ts
import type { Plugin } from "@opencode-ai/plugin";

export const BeansPrimePlugin: Plugin = async ({ $, directory }) => {
  let prime = undefined;

  try {
    const hasBeans = await $`which beans`.quiet();
    const hasConfig = await $`test -f ${directory}/.beans.yml`.quiet();

    if (hasBeans.exitCode === 0 && hasConfig.exitCode === 0) {
      const result = await $`beans prime`.cwd(directory).quiet();
      prime = result.stdout.toString();
    }
  } catch (e) {
    // Silently skip if beans not available
  }

  return {
    "experimental.chat.system.transform": async (_, output) => {
      if (prime) output.system.push(prime);
    },
    "experimental.session.compacting": async (_, output) => {
      if (prime) output.context.push(prime);
    },
  };
};

export default BeansPrimePlugin;

将以下插件复制到你的OpenCode配置中：

typescript

// ~/.opencode/plugin/beans-prime.ts
import type { Plugin } from "@opencode-ai/plugin";

export const BeansPrimePlugin: Plugin = async ({ $, directory }) => {
  let prime = undefined;

  try {
    const hasBeans = await $`which beans`.quiet();
    const hasConfig = await $`test -f ${directory}/.beans.yml`.quiet();

    if (hasBeans.exitCode === 0 && hasConfig.exitCode === 0) {
      const result = await $`beans prime`.cwd(directory).quiet();
      prime = result.stdout.toString();
    }
  } catch (e) {
    // Silently skip if beans not available
  }

  return {
    "experimental.chat.system.transform": async (_, output) => {
      if (prime) output.system.push(prime);
    },
    "experimental.session.compacting": async (_, output) => {
      if (prime) output.context.push(prime);
    },
  };
};

export default BeansPrimePlugin;

Integration with Codex

与Codex集成

Set environment or add to AGENTS.md:

bash

undefined

设置环境变量或添加到AGENTS.md中：

bash

undefined

In your repo's AGENTS.md:

在你的仓库AGENTS.md中添加：

IMPORTANT: before you do anything else, run

beans prime

and heed its output.

undefined

IMPORTANT: before you do anything else, run

beans prime

and heed its output.

undefined

Integration with Claude Code

与Claude Code集成

Add to Claude Code's system prompt or context:

bash

undefined

添加到Claude Code的系统提示词或上下文：

bash

undefined

Run before coding session

在编码会话开始前运行

beans prime >> ~/.claude/context/beans.txt

undefined

beans prime >> ~/.claude/context/beans.txt

undefined

When to create beans

何时创建beans

Create beans when:

the user requests a new feature which has no bean yet
the user requests refactorings, bugfixes or other changes which do not have beans
the user makes big changes to the repo structure

IMPORTANT: ALWAYS commit a newly created bean immediately after creation. Do not wait until other work is done — the bean file itself should be committed in its own atomic commit right away (e.g.

git add .beans/<bean-file> && git commit -m "beans: create <bean-title>"

Exceptions for not creating beans:

committing things via git
changing rules in AGENTS.md

在以下场景创建beans：

用户请求了一个尚未创建bean的新功能
用户请求重构、修复bug或其他未创建bean的变更
用户对仓库结构进行了重大修改

重要提示：创建新bean后请立即提交。 不要等到其他工作完成后再提交——bean文件本身应在创建后立即单独提交（例如：

git add .beans/<bean-file> && git commit -m "beans: create <bean-title>"

）。

无需创建beans的例外情况：

通过Git提交内容时
修改AGENTS.md中的规则时

Workflow Example

工作流示例

bash

undefined

bash

undefined

1. Start work on a feature

1. 开始开发一项功能

beans create "Add dark mode support" --tag ui --type feature

2. Work on it, update progress

2. 进行开发，更新进度

beans update <bean-id> --status in-progress --body "Started working on color scheme"

3. Complete the feature

3. 完成功能开发

beans update <bean-id> --status completed beans update <bean-id> --body "Dark mode implemented for all views"

undefined

beans update <bean-id> --status completed beans update <bean-id> --body "Dark mode implemented for all views"

undefined

Bean File Format

Bean文件格式

Beans are stored in

.beans/

as markdown:

markdown

---
id: 12345678
title: "Implement user login"
status: todo
tags: [feature, auth]
priority: high
created: 2024-01-15T10:00:00Z
updated: 2024-01-15T14:30:00Z
---

beans以Markdown文件形式存储在

.beans/

目录中：

markdown

---
id: 12345678
title: "Implement user login"
status: todo
tags: [feature, auth]
priority: high
created: 2024-01-15T10:00:00Z
updated: 2024-01-15T14:30:00Z
---

Description

Implement user login with email and password.

Notes

Use existing auth infrastructure
Follow security best practices

undefined

Use existing auth infrastructure
Follow security best practices

undefined

Configuration

配置

Create

.beans.yml

in your project root:

yaml

undefined

在项目根目录创建

.beans.yml

文件：

yaml

undefined

.beans.yml

directory: .beans format: markdown templates: default: | --- id: {{.ID}} title: "{{.Title}}" status: open created: {{.Created}} ---

{{.Description}}

undefined

directory: .beans format: markdown templates: default: | --- id: {{.ID}} title: "{{.Title}}" status: open created: {{.Created}} ---

{{.Description}}

undefined

Tips

小贴士

Commit
.beans.yml
— Share config with team
Ignore
.beans/*.md
— Keep beans local or commit based on preference
Use tags consistently — Create tag taxonomy early
Run
beans prime
— Before starting AI-assisted work

提交
.beans.yml
— 与团队共享配置
忽略
.beans/*.md
— 根据偏好选择是否将beans提交到仓库或仅保留在本地
一致使用标签 — 尽早建立标签分类体系
运行
beans prime
— 在开始AI辅助开发前执行

Related Skills

链接

GitHub: https://github.com/hmans/beans
Documentation: https://github.com/hmans/beans#readme

GitHub: https://github.com/hmans/beans
文档: https://github.com/hmans/beans#readme