projects (Hasna)

开放项目

用于AI代理的项目管理CLI+MCP服务器。注册项目一次，在任何地方打开它们，同步到S3，自动初始化git，并连接到 hasna 生态系统（待办事项、纪念品、对话）。

安装

bun install -g @hasna/projects

命令行界面

# Register a project
projects create --name my-app --path /path/to/my-app
projects create --name my-app                         # uses cwd as path

# List / search
projects list
projects list --status archived
projects list --tags web,ts                           # AND filter
projects list --json | jq '.[].path'                 # machine-readable

# Get / status
projects get my-app                                   # auto-detects from cwd
projects get my-app --json
projects status                                       # all projects at a glance
projects status my-app                                # single project detail
projects context my-app                               # full agent handoff context
projects where my-app                                 # paths/workdirs across machines
projects recent                                       # recently opened (with relative times)
projects doctor                                       # health-check all projects
projects doctor my-app --fix --dry-run                # preview safe repairs with issue codes
projects doctor my-app --fix                          # auto-repair what can be fixed
projects stale                                        # stale paths, workdirs, tmux sessions/windows
projects cleanup --dry-run                            # preview safe stale-record cleanup
projects setup-machine                                # check Bun/tmux/git/gh/aws/config readiness
projects stats                                        # disk / sync totals
projects stats my-app

# Modify
projects update my-app --description "My app" --tags "web,ts"
projects rename my-app my-app-v2                      # updates slug + .project.json
projects tag my-app infra cloud                       # add tags
projects untag my-app cloud                           # remove a tag
projects archive my-app
projects unarchive my-app

# Open (cd into it)
cd $(projects open my-app)                            # print path; auto-detects cwd
workon my-app                                         # shell function — actually cd's
penv my-app                                           # load project .env into shell
projects env my-app                                   # print export statements (eval)
projects env my-app --list                            # list keys only

# Working directories (multi-machine / multi-repo)
projects workdir add my-app /path/to/dir --label backend
projects workdir list my-app
projects workdir generate my-app                      # write CLAUDE.md + AGENTS.md
projects workdir generate my-app --dry-run
projects workdir remove my-app /path/to/dir

# Import existing directories
projects import /path/to/existing-project
projects import-bulk /path/to/workspace               # imports all subdirs
projects clone my-app /new/local/path                 # pull from S3 to new machine path

# Sync to/from S3
projects update my-app --s3-bucket my-bucket
projects sync my-app
projects sync my-app --direction push
projects sync-all                                     # sync all projects with S3 configured
projects watch my-app                                 # push changes live as you edit
projects sync-log my-app                              # show sync history

# Schedule auto-sync
projects schedule set --interval daily --direction both
projects schedule status
projects schedule remove

# Cloud sync (SQLite ↔ RDS PostgreSQL)
projects cloud status
projects cloud pull
projects cloud push

# tmux
projects tmux open --name my-app
projects tmux window-status my-app my-app --json      # alive/dead/missing window health
projects tmux dead-windows my-app                     # exited panes / dead windows
projects tmux revive-window my-app my-app             # recreates only missing/dead windows
projects tmux revive-window my-app my-app --force     # explicit live-window restart
projects tmux revive-window my-app my-app --force --cwd "$PWD" --command "claude"
projects tmux revive-window master worker             # preserves active windows for every linked session

# Publish to GitHub
projects publish my-app --org hasnaxyz
projects unpublish my-app

# Git passthrough
projects git my-app status
projects git my-app log --oneline -10

# Shell completion (includes workon + penv functions)
eval "$(projects completion)"                         # bash
eval "$(projects completion --shell zsh)"             # zsh

MCP服务器

添加到您的Claude配置中：

{
  "mcpServers": {
    "open-projects": {
      "command": "projects-mcp"
    }
  }
}

可用工具

projects_create响应

{
  "id": "prj_abc123",
  "name": "my-app",
  "path": "/path/to/my-app",
  "workingDirectory": "/path/to/my-app",
  "instruction": "Project created. workingDirectory: /path/to/my-app",
  "post_create_actions": [
    {
      "description": "Register with open-todos for task tracking",
      "tool": "mcp__todos__create_project",
      "args": { "name": "my-app", "path": "/path/to/my-app" },
      "on_complete": "Call projects_link with todos_project_id="
    }
  ]
}

建筑

src/
├── cli/
│   ├── index.ts              # CLI entry point (commander)
│   └── commands/
│       ├── projects.ts       # All project commands
│       └── completion.ts     # Shell completion
├── db/
│   ├── database.ts           # SQLite init, path resolution
│   ├── schema.ts             # Migrations
│   └── projects.ts           # CRUD + sync log
├── lib/
│   ├── git.ts                # git init, .gitignore, passthrough
│   ├── sync.ts               # S3 incremental sync
│   ├── project-context.ts    # Agent handoff context
│   ├── setup-machine.ts      # Machine readiness checks
│   ├── stale.ts              # Stale project/workdir/tmux findings
│   ├── import.ts             # Import existing projects
│   ├── github.ts             # GitHub publish via gh CLI
│   └── scheduler.ts          # Cron auto-sync
├── mcp/
│   └── index.ts              # MCP server (all tools)
├── types/
│   └── index.ts              # Types + error classes
└── index.ts                  # SDK exports

数据模型

项目 — id (prj_ +nanoid12）， slug, name, description, status, path, s3_bucket, s3_prefix, git_remote, tags, integrations, created_at, updated_at, synced_at

项目文件 — project_id, relative_path, size, hash, synced_at

sync_log — project_id, direction, status, files_synced, bytes, error, started_at, completed_at

数据库路径： ~/.hasna/projects/projects.db 以（权力）否决 HASNA_PROJECTS_DB_PATH)

生态系统整合

projects_create 回报 post_create_actions --代理应进行一系列MCP调用以注册项目：

• 开放-所有 (mcp__todos__create_project)--任务跟踪
• 开放式纪念品 (mcp__mementos__register_project)--持久存储器
• 公开对话 (mcp__conversations__create_space)--团队协调（可选）

每次通话后，使用 projects_link 将返回的ID存储在项目记录中，以及 .project.json.

S3同步

• S3路径： s3://{bucket}/{prefix}/projects/{project-id}/{relative-path}
• 增量：比较本地MD5与S3 ETag，跳过未更改的文件
• 跳过大于100MB的文件
• 包含 .git/ 为了完全恢复
• 将同步历史记录写入 sync_log 桌子

许可证

阿帕奇-2.0