work4me

CLI tool for AI-powered developer workflows — Jira + Claude Code

Work4Me is a local-first CLI that bridges your Jira board and Claude Code. It fetches ticket context, picks the right prompt template (rule-based + AI), and generates ready-to-run prompts — so you spend less time writing context and more time shipping.

npx @grep_it/work4me init                  # one-time setup
work4me suggest PROJ-42 --run              # fetch ticket → generate prompt → launch Claude
work4me generate "add pagination to users API" --copy  # generate prompt → copy to clipboard

Contents

• Requirements
• Installation
• Quick start
• CLI reference
  • suggest
  • generate
  • init · start · sync
• Configuration
• Prompt templates
• Claude hooks integration
• Dashboard (secondary UI)
• Security

Requirements

• Node.js ≥ 18
• A Jira account with API access (Cloud or self-hosted)
• An API key for your chosen AI provider (see Configuration) — needed for suggest (AI phase) and generate
• The AI provider's CLI — needed for --run flag (optional). Defaults to Claude Code for the claude provider.

Installation

Run without installing (recommended for first use):

npx @grep_it/work4me init

Install globally:

npm install -g @grep_it/work4me
work4me init

Install locally in a project:

npm install --save-dev @grep_it/work4me
npx work4me init

Quick start

cd your-project
npx @grep_it/work4me init   # creates config, .env scaffold, hooks, and docs/prompts/
work4me suggest PROJ-42     # suggest a prompt template for a ticket
work4me generate "refactor auth middleware to use JWT"  # generate a prompt from free text

init creates work4me.config.json, .work4me.env, a docs/ scaffold, and wires up .claude/hooks/ automatically.

CLI reference

work4me suggest <ticket-key>

Fetches a Jira ticket, scores your prompt templates using rule-based logic and Claude Haiku, renders the best match with live ticket variables, and prints the result.

work4me suggest <ticket-key> [options]

Arguments:
  ticket-key              Jira issue key, e.g. PROJ-42

Options:
  --no-ai                 Skip AI suggestion — use rule-based scoring only
  --copy                  Copy generated prompt to clipboard
  --run                   Pipe prompt directly into Claude Code in this terminal
  --cwd <path>            Project directory (overrides WORK4ME_PROJECT_DIR env var)
  -h, --help              Show help

Examples:

# Suggest a prompt for PROJ-42 and print it
work4me suggest PROJ-42

# Skip the AI phase (faster, no API call)
work4me suggest PROJ-42 --no-ai

# Copy the generated prompt to clipboard
work4me suggest PROJ-42 --copy

# Pipe the prompt straight into Claude Code
work4me suggest PROJ-42 --run

# Point at a project in another directory
work4me suggest PROJ-42 --cwd ~/projects/my-service

# Combine: generate and immediately launch Claude
work4me suggest PROJ-42 --run --cwd ~/projects/my-service

How it works:

1. Fetches the ticket from Jira (summary, description, status, type, priority, comments)
2. Scores your docs/prompts/*.md templates by rule: ticket status → suggested type (implement, review, test, bugfix, wrapup, …)
3. Sends ticket context + template list to Claude Haiku for a second opinion (skip with --no-ai)
4. Renders the winning template with {{ticket.*}} variables replaced by live values
5. Prints the prompt; optionally copies or pipes into Claude Code

Sample output:

  ┌────────────────────────────────────────────────────────────────┐
  │ PROJ-42  Add pagination to the users API endpoint              │
  │ Status  In Progress   Priority  Medium   Type  Story           │
  │ Assignee  Jane Smith                                           │
  └────────────────────────────────────────────────────────────────┘

  ✔ Rule suggestion  →  implement  (Status: In Progress)
  ✔ AI suggestion    →  implement  "ticket is mid-development, implement template is the right fit"
                        (matches rule suggestion, confirmed)

  ─────────────── Generated Prompt ──────────────────────────────────

  # Implement: PROJ-42 — Add pagination to the users API endpoint
  ...

  ────────────────────────────────────────────────────────────────────

  ✔ Prompt ready  (1,243 chars)

work4me generate "<task>"

Two-phase AI prompt generation from a plain-text task description. Phase 1 (Haiku) scans your docs/ folder and selects relevant files. Phase 2 (Sonnet, streamed) generates a detailed prompt grounded in your project context.

work4me generate <task> [options]

Arguments:
  task                    Free-text task description (quote if it contains spaces)

Options:
  --ticket <key>          Attach a Jira ticket as additional context (e.g. PROJ-42)
  --model <name>          Model override (provider-dependent — e.g. haiku | sonnet | opus for Claude)  (default: config ai.model)
  --copy                  Copy generated prompt to clipboard
  --run                   Pipe prompt directly into Claude Code in this terminal
  --cwd <path>            Project directory (overrides WORK4ME_PROJECT_DIR env var)
  -h, --help              Show help

Examples:

# Generate a prompt from a task description
work4me generate "add rate limiting to the public API"

# Attach a Jira ticket for extra context
work4me generate "add rate limiting" --ticket PROJ-88

# Use a faster/cheaper model for generation
work4me generate "write unit tests for UserService" --model haiku

# Generate and pipe straight into Claude Code
work4me generate "refactor the auth middleware to use JWT" --run

# Generate, copy to clipboard, and use a different project dir
work4me generate "migrate DB schema to snake_case" --copy --cwd ~/projects/api

# Override model and copy
work4me generate "document the REST endpoints with OpenAPI" --model opus --copy

How it works:

1. Scans docs/ and builds a doc index (filenames + snippets)
2. Asks Claude Haiku which docs are relevant to the task (outputs a JSON list)
3. Always includes CLAUDE.md and workflow.md if present
4. Loads selected docs, caps at 80 k chars total
5. Streams a detailed, actionable prompt from Sonnet (or your chosen model) to stdout
6. Optionally copies or launches in Claude Code

Sample output:

  ✔ Found 12 docs in docs/
  ✔ Selected 3 docs:
      → architecture.md
      → workflow.md  (always included)
      → CLAUDE.md    (always included)
  ✔ Context ready  (14,320 / 80,000 chars)

  ─────────────── Generating Prompt · sonnet ─────────────────────────

  Implement rate limiting on the public REST API using express-rate-limit.
  Follow the existing middleware pattern in src/middleware/. Apply a limit
  of 100 requests per 15-minute window per IP...

  ────────────────────────────────────────────────────────────────────

  ✔ Done  (892 chars)

work4me init · start · sync

| Command | Description | | ------------------- | -------------------------------------------------------------------------------------------------------------------------- | | work4me init | Interactive setup wizard. Creates config, scaffold, and Claude hooks. Safe to re-run — existing files are not overwritten. | | work4me start | Start the browser dashboard (secondary UI). Detects production vs dev mode automatically. | | work4me sync | Pull the latest docs from your configured adapter (Confluence, GitHub, or local). | | work4me --version | Print the installed version. | | work4me --help | Show usage. |

Configuration

work4me.config.json

Created by work4me init. Keep in your project root (added to .gitignore automatically because it contains your Jira email).

{
  "project": {
    "name": "My Project"
  },
  "jira": {
    "baseUrl": "https://yourcompany.atlassian.net",
    "email": "[email protected]",
    "apiToken": "${JIRA_API_TOKEN}",
    "project": "PROJ",
    "boardId": 1,
    "sprintFilter": "active"
  },
  "docs": {
    "adapter": "local",
    "localPath": "./docs"
  },
  "dashboard": {
    "port": 3001,
    "pollInterval": 10000
  },
  "ai": {
    "provider": "claude",
    "model": "sonnet",
    "runCommand": "claude",
    "providers": {
      "claude": {},
      "openai": { "apiKey": "${OPENAI_API_KEY}" },
      "gemini": { "apiKey": "${GEMINI_API_KEY}" }
    }
  }
}

ai.provider selects the AI backend. Valid values: claude (default), openai, gemini.

ai.model controls the generation model for work4me generate. Valid values depend on the provider:

| Provider | Models | | -------- | ---------------------------------------------- | | claude | haiku, sonnet (default), opus | | openai | gpt-4o (default), gpt-4o-mini | | gemini | gemini-2.0-flash (default), gemini-2.5-pro |

Overridable per command with --model.

ai.runCommand is the CLI binary launched by --run. Defaults to claude, codex, or gemini depending on the provider. Override if your binary has a different name (e.g. claude-dev).

Finding your Jira values:

• boardId — open your Jira board, check the URL: .../jira/software/projects/PROJ/boards/42
• project — the uppercase project key shown in ticket keys (e.g. PROJ in PROJ-42)

.work4me.env

Secrets live here — never in work4me.config.json. Created by work4me init with permissions 0600 and added to .gitignore.

JIRA_API_TOKEN=your_jira_api_token_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here   # claude provider
OPENAI_API_KEY=your_openai_api_key_here         # openai provider
GEMINI_API_KEY=your_gemini_api_key_here         # gemini provider (or use gcloud ADC)
GITHUB_TOKEN=your_github_token_here             # only needed for github docs adapter
NOTES_KEY=auto_generated_by_work4me_init        # only needed for encrypted notes

Only the key for your chosen ai.provider is required for AI features.

| Variable | Required | Purpose | | ------------------- | -------- | ----------------------------------------------------------------------------------- | | JIRA_API_TOKEN | Yes | Jira API access (for suggest and --ticket) | | ANTHROPIC_API_KEY | No | Claude provider — required for generate; enables AI phase for suggest | | OPENAI_API_KEY | No | OpenAI provider — required when ai.provider is openai | | GEMINI_API_KEY | No | Gemini provider — required when ai.provider is gemini (unless using gcloud ADC) | | GITHUB_TOKEN | No | Private GitHub repos (docs adapter = github) | | NOTES_KEY | No | AES-256-GCM encryption key for dashboard notes (auto-generated) |

Config values written as "${JIRA_API_TOKEN}" are resolved from this file at startup. Shell environment variables always take precedence — useful in CI/CD.

Getting a Jira API token: Atlassian account → Security → API tokens.

Getting an Anthropic API key: console.anthropic.com → API Keys.

Getting an OpenAI API key: platform.openai.com → API keys.

Getting a Gemini API key: aistudio.google.com → Get API key. Alternatively, authenticate with gcloud auth application-default login to use Application Default Credentials — no API key needed.

Prompt templates

Templates live in docs/prompts/ and are Markdown files with YAML frontmatter declaring their type. The suggest command picks a template based on type.

---
name: Implement
type: implement
---

# Implement: {{ticket.key}} — {{ticket.summary}}

## Ticket

{{ticket.description}}

## Instructions

1. Create branch `feat/{{ticket.key}}-{{ticket.slug}}` off `develop`
2. Implement the acceptance criteria
3. Write tests
4. Open a PR and update Jira

Available template types (matched by suggest):

| Type | Triggered when | | ----------- | ------------------------------------------- | | analyse | Status: To Do | | implement | Status: In Progress | | review | Status: Review | | test | Status: Testing | | wrapup | Status: Done | | bugfix | Issue type contains "bug" | | resolve | Latest comment mentions "fix comment", etc. |

Available {{ticket.*}} variables:

| Variable | Value | | ------------------------ | ---------------------------------------- | | {{ticket.key}} | e.g. PROJ-42 | | {{ticket.summary}} | Ticket title | | {{ticket.description}} | Full description (ADF → plain text) | | {{ticket.status}} | e.g. In Progress | | {{ticket.priority}} | e.g. High | | {{ticket.assignee}} | Assignee display name | | {{ticket.type}} | Issue type (Story, Bug, Task, …) | | {{ticket.labels}} | Comma-separated labels | | {{ticket.slug}} | URL-safe summary slug (for branch names) |

Claude hooks integration

work4me init creates .claude/hooks/ scripts that fire on every Claude Code tool use and session stop. The scripts read .work4me/hooks-config.yaml and execute Jira transitions and comments automatically.

hooks-config.yaml

hooks:
  - name: start-development
    trigger: session-start
    jira_transition: 21 # → In Progress
    jira_comment: |
      Starting development on {{ticket.key}}.
      Branch: feat/{{ticket.key}}-{{ticket.slug}}

  - name: pr-opened
    trigger: git-push
    jira_transition: 3 # → Review
    jira_comment: |
      PR opened: {{pr_url}}

  - name: tests-passed
    trigger: tests-pass
    jira_transition: 31 # → Done
    jira_comment: |
      All tests passed. Ticket complete.

  - name: session-end
    trigger: agent-stop
    jira_comment: |
      Agent session ended. {{session_summary}}

Edit at .work4me/hooks-config.yaml. Changes take effect on the next hook invocation — no restart needed.

Project structure (after init)

your-project/
├── work4me.config.json          ← board, docs adapter, port, AI model
├── .work4me.env                 ← secrets (gitignored, mode 0600)
├── .work4me/
│   ├── hooks-config.yaml        ← hook → Jira transition + comment templates
│   ├── todos.json               ← to-do items (managed via dashboard)
│   └── notes.json               ← encrypted notes (managed via dashboard)
├── .claude/
│   ├── settings.json            ← Claude Code hook registrations
│   └── hooks/
│       ├── post-tool-use.js     ← fires on every tool use
│       ├── agent-stop.js        ← fires at session end
│       └── hook-helpers.js      ← shared Jira utilities
└── docs/
    ├── CLAUDE.md                ← agent context (auto-loaded by Claude Code)
    ├── workflow.md              ← workflow rules per stage
    └── prompts/
        ├── implement.md
        ├── dev-review.md
        ├── resolve-comments.md
        └── testing.md

Dashboard (secondary UI)

work4me start opens a browser dashboard at http://localhost:3001 (port configurable). The dashboard provides the same functionality as the CLI in a visual form — useful for teams who prefer a GUI.

Tabs:

• Home — project overview with quick-access cards and recent activity
• Board — live Jira board (active sprint, auto-refreshes). Click any ticket to open a detail drawer and generate a prompt
• Prompts — browse and generate prompts from your template library
• Docs — read synced project docs with a tree-view file browser
• To-Do — manage project to-dos (stored locally in .work4me/todos.json)
• Notes — encrypted project notes (AES-256-GCM when NOTES_KEY is configured)
• Config — manage hooks, workflow rules, API tokens, and AI model through a visual editor
• Editor — edit prompt templates and docs directly in the browser (Markdown, YAML, JSON)

Security

• The dashboard binds to 127.0.0.1 only — not reachable from the network
• A random 32-byte session secret is generated on every work4me start; the Vite dev proxy and backend validate it on every request
• Jira credentials are read from .work4me.env at startup and never sent to the browser
• Notes are encrypted at rest with AES-256-GCM; decryption happens server-side
• CORS is locked to the single frontend origin
• Path traversal guards are enforced at the docs adapter layer
• Security headers via helmet (X-Content-Type-Options, X-Frame-Options, Referrer-Policy, …)
• Rate limiting: 300 requests/minute protects against runaway polling or hook loops
• YAML parsing uses CORE_SCHEMA to block executable tags (!!js/function, !!js/regexp)

Supported Node.js versions

Node.js 18, 20, and 22 (LTS lines). No transpilation — requires ES2020 support.

License

MIT