diff --git a/.pi/agent/agents/design-engineer.md b/.pi/agent/agents/design-engineer.md new file mode 100644 index 0000000..de13fb3 --- /dev/null +++ b/.pi/agent/agents/design-engineer.md @@ -0,0 +1,47 @@ +--- +name: design-engineer +description: Frontend and design-engineering specialist for UI/UX direction, design systems, and implementation-ready recommendations +tools: read, grep, find, ls +model: google-antigravity/gemini-3-flash +--- + +You are a design engineer. + +Your job is to turn product requirements and current frontend context into practical, implementation-aware recommendations across UI, UX, frontend structure, and design systems. +You do not implement changes. +You analyze flows, interaction design, component responsibilities, states, visual hierarchy, consistency, and rollout shape. + +Focus on: +- user journeys and interaction flow +- component responsibilities and frontend structure +- design system consistency, tokens, spacing, typography, and visual hierarchy +- affordances, feedback, loading, empty, error, and edge states +- accessibility, responsiveness, and clarity +- implementation realism and incremental rollout guidance +- strong product taste and cohesive visual decisions + +Output format: + +## Goal +- Restate the user and product problem clearly + +## Proposed Direction +- Recommended UI, UX, and frontend direction + +## Key Screens or Components +- Main surfaces, components, and states to account for + +## Design System Notes +- Guidance on consistency, reuse, and polish + +## Alternatives +- Reasonable alternatives and tradeoffs + +## Implementation Guidance +1. Small actionable steps for engineering + +## Risks +- What could confuse users or make the design harder to ship + +## Validation +- How to test whether the design works diff --git a/.pi/agent/agents/uiux-designer.md b/.pi/agent/agents/uiux-designer.md deleted file mode 100644 index 419d4aa..0000000 --- a/.pi/agent/agents/uiux-designer.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -name: uiux-designer -description: UI/UX design specialist for product flows, interaction design, and implementation-ready recommendations -tools: read, grep, find, ls -model: google-antigravity/gemini-3.1-pro-high ---- - -You are a UI/UX design specialist. - -Your job is to turn requirements and current product context into a practical UI/UX design direction. -You do not implement changes. -You analyze flows, interaction details, information hierarchy, usability tradeoffs, and rollout shape. - -Focus on: -- user journeys and interaction flow -- screen or component responsibilities -- hierarchy, affordances, and feedback states -- empty, loading, error, and edge states -- accessibility and clarity -- incremental rollout guidance for engineering - -Output format: - -## Goal -- Restate the user and product problem clearly - -## Proposed UX/UI Direction -- Recommended approach - -## Key Screens or States -- Main surfaces, components, and states to account for - -## Alternatives -- Reasonable alternatives and tradeoffs - -## Implementation Guidance -1. Small actionable steps for engineering - -## Risks -- What could confuse users or make the design harder to ship - -## Validation -- How to test whether the design works diff --git a/.pi/agent/extensions/clipboard-images.ts b/.pi/agent/extensions/clipboard-images.ts new file mode 100644 index 0000000..ae474d7 --- /dev/null +++ b/.pi/agent/extensions/clipboard-images.ts @@ -0,0 +1,39 @@ +/** + * Clipboard Image Labels + * + * Adds [Image #N] labels to messages that include pasted images, + * matching the Claude Code / Codex visual style. + * + * Usage: + * - Paste: Ctrl+V (Alt+V on Windows) + * - Drag: drag any image file onto the terminal + * + * When images are detected, [Image #1], [Image #2], … labels are + * appended to the message text so they appear in the conversation + * history and are visible to the LLM alongside the actual image data. + * + * A small notification confirms how many images were attached. + */ +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"; + +export default function (pi: ExtensionAPI) { + pi.on("input", async (event, ctx) => { + // Nothing to do when no images are attached + if (!event.images || event.images.length === 0) { + return { action: "continue" }; + } + + // Build [Image #N] labels – one per attached image + const labels = event.images.map((_img, i) => `[Image #${i + 1}]`).join(" "); + + // Append labels after any typed text (or use them alone if no text) + const newText = event.text?.trim() ? `${event.text.trim()}\n\n${labels}` : labels; + + // Brief confirmation so the user knows the paste registered + const count = event.images.length; + ctx.ui.notify(`πŸ“Ž ${count} image${count > 1 ? "s" : ""} attached`, "info"); + + // Transform keeps the original images intact; only the text changes + return { action: "transform", text: newText }; + }); +} diff --git a/.pi/agent/extensions/subagent/README.md b/.pi/agent/extensions/subagent/README.md index b25c791..aa807e4 100644 --- a/.pi/agent/extensions/subagent/README.md +++ b/.pi/agent/extensions/subagent/README.md @@ -4,7 +4,7 @@ Installed roles: - `reviewer` β€” review changes, bugs, risks, maintainability - `librarian` β€” explore and map a codebase -- `uiux-designer` β€” UI/UX design direction, flows, states, and implementation guidance +- `design-engineer` β€” frontend-aware UI/UX direction, design systems, and implementation-ready recommendations - `executor` β€” implement ordered coding tasks from a defined todo list - `planner` β€” interactive planning specialist that can ask clarifying questions and return an ordered executor-ready todo list @@ -16,8 +16,8 @@ Installed roles: ## Example prompts - `Use the subagent tool with reviewer to inspect the auth refactor.` -- `Use subagent in parallel: librarian maps the settings flow, uiux-designer proposes an improved UX direction, reviewer lists product and implementation risks.` -- `Chain librarian -> uiux-designer to redesign onboarding. Use {previous} in the second task.` +- `Use subagent in parallel: librarian maps the settings flow, design-engineer proposes an improved UX direction, reviewer lists product and implementation risks.` +- `Chain librarian -> design-engineer to redesign onboarding. Use {previous} in the second task.` - `Use executor to implement this ordered todo list exactly as written, then summarize what was completed and validated.` - `Use planner to clarify ambiguity only when needed and output an ordered implementation todo list for executor handoff.` @@ -37,7 +37,7 @@ Installed roles: - Parallel mode allows up to 8 tasks and runs up to 4 concurrently - `reviewer` uses `openai-codex/gpt-5.4:xhigh` - `librarian` uses `anthropic/claude-sonnet-4-6` -- `uiux-designer` uses `google-antigravity/gemini-3.1-pro-high` +- `design-engineer` uses `google-antigravity/gemini-3-flash` - `executor` uses `openai-codex/gpt-5.3-codex:high` - `planner` uses `anthropic/claude-sonnet-4-6` diff --git a/.pi/agent/extensions/subagent/index.ts b/.pi/agent/extensions/subagent/index.ts index 682b73a..2f8513f 100644 --- a/.pi/agent/extensions/subagent/index.ts +++ b/.pi/agent/extensions/subagent/index.ts @@ -335,7 +335,7 @@ export default function (pi: ExtensionAPI) { description: [ "Delegate work to specialized subagents with isolated context.", "Supports single, parallel, and chained execution.", - "Useful built-in roles: reviewer, librarian, uiux-designer, executor.", + "Useful built-in roles: reviewer, librarian, design-engineer, executor.", 'Default scope is "user" (~/.pi/agent/agents). Set agentScope to "both" or "project" to include repo-local agents.', ].join(" "), parameters: SubagentParams, diff --git a/.pi/agent/prompts/repo-init-deep.md b/.pi/agent/prompts/repo-init-deep.md new file mode 100644 index 0000000..189dd13 --- /dev/null +++ b/.pi/agent/prompts/repo-init-deep.md @@ -0,0 +1,178 @@ +--- +description: Set up or optimize a large repository or monorepo for agent-first development using hierarchical AGENTS.md files and progressive disclosure +--- + +Set up or optimize the current repository for agent-first development, assuming it may be a large repo or monorepo. Use hierarchical `AGENTS.md` files only where they add real value. Based on principles from OpenAI's harness engineering and HumanLayer's CLAUDE.md guide. + +Additional user context and constraints: +$ARGUMENTS + +Before changing anything: +1. Inspect the repository structure first. +2. Identify true subsystem boundaries before proposing nested `AGENTS.md` files. +3. Prefer minimal, high-leverage, versioned changes. +4. Preserve useful project-specific guidance instead of replacing it blindly. +5. Do **not** generate `AGENTS.md` files for every directory. + +## When to Use +- Large repositories with multiple domains, apps, services, or packages +- Monorepos with different build/test workflows per subtree +- Repos where one root `AGENTS.md` is too broad to stay short and useful +- Repos that need progressive disclosure for agent context + +## Goal +Design an agent-legible documentation layout where: +- the root `AGENTS.md` stays short and repo-wide, +- nested `AGENTS.md` files exist only for meaningful boundaries, +- each nested file contains local rules, commands, and navigation help for that subtree, +- duplication across levels is minimized. + +## Core Principles + +### 1. Root AGENTS.md Is the Map +- The root `AGENTS.md` should remain a concise project-wide entry point. +- It should describe the repo, major subsystems, shared commands, verification, and where deeper context lives. +- It should point agents toward important subtrees that have their own `AGENTS.md`. + +### 2. Nested AGENTS.md Files Are Scoped +Create nested `AGENTS.md` files only when a subtree has at least one of these: +- a distinct purpose or domain boundary, +- different commands or verification workflow, +- different conventions or architectural constraints, +- separate deploy/runtime concerns, +- enough complexity that local guidance reduces confusion. + +If a subtree has no distinct guidance, do **not** create a nested `AGENTS.md` there. + +### 3. Progressive Disclosure Over Duplication +- Parent files provide broad context. +- Child files add only local context. +- Do not copy the same rules into every nested file. +- Child files should extend or narrow the parent context, not restate it. + +### 4. Repository = System of Record +- If a decision matters for agents, put it in the repo. +- Architecture, conventions, plans, and decisions should live in versioned docs. +- Avoid relying on external-only knowledge. + +### 5. Enforce, Don’t Instruct +- Put invariants into CI, tests, linters, type checks, and scripts whenever possible. +- Document verification commands the agent can actually run. +- Avoid instructions that cannot be checked mechanically. + +### 6. Less Instructions = Better Compliance +- Keep every `AGENTS.md` compact. +- Root file should usually stay under ~100 lines. +- Nested files should be even narrower: only the local rules that matter for that subtree. + +## Suggested Hierarchy + +Only as needed, not by default: + +```text +project/ +β”œβ”€β”€ AGENTS.md # project-wide context and repo map +β”œβ”€β”€ CLAUDE.md -> AGENTS.md +β”œβ”€β”€ docs/ +β”‚ β”œβ”€β”€ ARCHITECTURE.md +β”‚ β”œβ”€β”€ CONVENTIONS.md +β”‚ β”œβ”€β”€ DECISIONS.md +β”‚ └── PLANS.md +β”œβ”€β”€ apps/ +β”‚ β”œβ”€β”€ AGENTS.md # app-layer guidance, if meaningful +β”‚ β”œβ”€β”€ web/ +β”‚ β”‚ └── AGENTS.md # only if web has distinct workflow/conventions +β”‚ └── api/ +β”‚ └── AGENTS.md # only if api has distinct workflow/conventions +└── packages/ + β”œβ”€β”€ AGENTS.md # shared package conventions, if meaningful + └── design-system/ + └── AGENTS.md # only if this subtree needs extra local guidance +``` + +## Heuristics for Where to Add Nested AGENTS.md + +Good candidates: +- `apps/`, `services/`, `packages/`, `libs/` +- frontend vs backend boundaries +- infra / deployment / ops directories +- design systems or component libraries +- generated-code boundaries with special rules +- domains with their own test/build/dev commands + +Poor candidates: +- shallow folders with no local rules +- directories that only mirror code organization but not workflow differences +- every leaf folder in the tree +- locations where the nested file would just repeat the parent file + +## What Each Level Should Contain + +### Root `AGENTS.md` +Include: +- project summary +- stack overview +- top-level repo map +- key shared commands +- verification commands +- links to `docs/` +- pointers to nested `AGENTS.md` files where relevant +- only universal repo-wide rules + +### Nested `AGENTS.md` +Include only local details such as: +- purpose of that subtree +- important local directories/files +- local dev/build/test commands +- local patterns or constraints +- where to find deeper docs for that subsystem +- any local generated-code or migration rules + +Do **not** repeat broad repo-wide guidance unless needed for clarity. + +## Recommended Process + +1. Inspect the repo structure and tooling. +2. Identify subsystem boundaries that actually justify local guidance. +3. Design the smallest useful hierarchy of `AGENTS.md` files. +4. Create or refine root `AGENTS.md` first. +5. Add nested `AGENTS.md` files only for meaningful subtrees. +6. Add or update `docs/` files for architecture/conventions/decisions as needed. +7. Ensure `CLAUDE.md` exists as a symlink to root `AGENTS.md`. +8. Keep files concise and avoid duplication. + +## AGENTS.md ↔ CLAUDE.md Symlink + +Always ensure both files exist so the repo works with any agent harness (Claude Code, OpenCode, Codex, etc.). + +**Rules:** +- `AGENTS.md` is the source of truth (canonical file). +- `CLAUDE.md` is a symlink to `AGENTS.md`. +- If only `CLAUDE.md` exists, rename it to `AGENTS.md` and create the symlink. +- If both exist as separate files, merge into `AGENTS.md` and replace `CLAUDE.md` with symlink. +- Add `CLAUDE.md` symlink to git (git tracks symlinks fine). + +## Checklist + +When initializing or optimizing a large repo or monorepo: + +- [ ] Root `AGENTS.md` exists and stays short +- [ ] Root `CLAUDE.md` is a symlink to `AGENTS.md` +- [ ] Root file contains only repo-wide guidance +- [ ] Nested `AGENTS.md` files exist only at meaningful subsystem boundaries +- [ ] Nested files add local context instead of duplicating parent guidance +- [ ] `docs/` exists with at least `ARCHITECTURE.md` +- [ ] Verification commands are documented and runnable +- [ ] CI/linters enforce important invariants where possible +- [ ] No critical workflow or architectural knowledge lives only outside the repo + +## Anti-Patterns +- ❌ Generating `AGENTS.md` in every directory +- ❌ Repeating the same instructions at root and child levels +- ❌ Putting domain-specific rules into the root file when they only matter in one subtree +- ❌ Creating deep hierarchy without distinct workflow boundaries +- ❌ Letting nested files drift from actual commands and tooling + +## Sources +- OpenAI: https://openai.com/index/harness-engineering/ +- HumanLayer: https://www.humanlayer.dev/blog/writing-a-good-claude-md diff --git a/.pi/agent/prompts/repo-init.md b/.pi/agent/prompts/repo-init.md new file mode 100644 index 0000000..27a0d74 --- /dev/null +++ b/.pi/agent/prompts/repo-init.md @@ -0,0 +1,147 @@ +--- +description: Set up or optimize the current repository for agent-first development (AGENTS.md, docs structure, progressive disclosure) +--- + +Set up or optimize the current repository for agent-first development. Based on principles from OpenAI's harness engineering and HumanLayer's CLAUDE.md guide. + +Additional user context and constraints: +$ARGUMENTS + +Before changing anything: +1. Inspect the repository state first. +2. Compare the repo against the checklist below. +3. Prefer minimal, high-leverage, versioned changes. +4. Preserve useful project-specific guidance instead of replacing it blindly. + +## When to Use +- Setting up a new repo for agent-driven development +- Optimizing an existing repo's AGENTS.md / CLAUDE.md +- Restructuring docs for agent legibility + +## Core Principles + +### 1. AGENTS.md = Table of Contents, Not Encyclopedia +- **Max ~100 lines.** Short, stable entry point. +- Only universally applicable instructions (applies to EVERY task). +- Points to deeper sources of truth β€” doesn't contain them. +- Domain-specific rules go in sub-files (`docs/`, skills, or scoped AGENTS.md in subdirs). + +### 2. Progressive Disclosure +- Agent starts with a small map and is taught where to look next. +- Use nested AGENTS.md files in subdirectories for scoped context. +- Skills for domain-specific workflows (loaded on demand, not always). +- Don't frontload β€” let the agent discover context as needed. + +### 3. Repository = System of Record +- If it's not in the repo, it doesn't exist to the agent. +- Push decisions, architecture, plans, conventions INTO the repo as versioned artifacts. +- No tribal knowledge in Slack, Google Docs, or people's heads. +- Docs are code β€” they get reviewed, updated, and maintained. + +### 4. Agent Legibility First +- Optimize for agent comprehension, not just human readability. +- Favor "boring" tech β€” composable, stable APIs, well-represented in training data. +- Make the app inspectable: logs, metrics, test output should be agent-parseable. +- Structured formats (JSON, markdown with clear headers) > prose walls. + +### 5. Enforce, Don't Instruct +- Invariants via CI/linters > instructions in AGENTS.md. +- Type checks, tests, formatting rules catch mistakes mechanically. +- Agent can run verification itself (`make check`, `npm test`, etc.). +- Instructions the agent can't verify will eventually be ignored. + +### 6. Less Instructions = Better Compliance +- LLMs reliably follow ~150-200 instructions max (frontier thinking models). +- Agent harnesses already consume ~50 instructions in system prompt. +- Every instruction in AGENTS.md competes for attention budget. +- When everything is "important," nothing is. + +## AGENTS.md Template + +```markdown +# AGENTS.md + +## Project +<1-2 sentences: what this project is and does> + +## Stack + + +## Structure + + +## Development + + +## Docs +Detailed documentation lives in `docs/`: +- `docs/ARCHITECTURE.md` β€” system design, package layering, domain map +- `docs/CONVENTIONS.md` β€” code style, patterns, naming +- `docs/PLANS.md` β€” active execution plans and progress +- `docs/DECISIONS.md` β€” architecture decision records (ADRs) + +## Verification + + +## Rules + +``` + +## docs/ Structure + +``` +docs/ +β”œβ”€β”€ ARCHITECTURE.md # System design, domain map, package layering +β”œβ”€β”€ CONVENTIONS.md # Code style, patterns, naming conventions +β”œβ”€β”€ DECISIONS.md # Architecture Decision Records (ADRs) +β”œβ”€β”€ PLANS.md # Active plans, completed plans, tech debt +└── / # Domain-specific deep docs as needed +``` + +## AGENTS.md ↔ CLAUDE.md Symlink + +Always ensure both files exist so the repo works with any agent harness (Claude Code, OpenCode, Codex, etc.). + +**Rules:** +- `AGENTS.md` is the source of truth (canonical file). +- `CLAUDE.md` is a symlink to `AGENTS.md`. +- If only `CLAUDE.md` exists, rename it to `AGENTS.md` and create the symlink. +- If both exist as separate files, merge into `AGENTS.md` and replace `CLAUDE.md` with symlink. +- Add `CLAUDE.md` symlink to git (git tracks symlinks fine). + +**Commands:** +```bash +# If AGENTS.md exists but no CLAUDE.md +ln -s AGENTS.md CLAUDE.md + +# If only CLAUDE.md exists +mv CLAUDE.md AGENTS.md +ln -s AGENTS.md CLAUDE.md + +# Verify +ls -la CLAUDE.md # should show -> AGENTS.md +``` + +## Checklist + +When initializing or optimizing a repo: + +- [ ] AGENTS.md exists and is <100 lines +- [ ] CLAUDE.md is symlinked to AGENTS.md (or vice versa) +- [ ] AGENTS.md contains: project summary, stack, structure map, dev commands, verification +- [ ] Domain-specific instructions are NOT in root AGENTS.md +- [ ] `docs/` directory exists with at minimum ARCHITECTURE.md +- [ ] Verification commands are documented and runnable by agent +- [ ] CI/linters enforce key invariants (not just documented) +- [ ] No critical knowledge lives only outside the repo + +## Anti-Patterns +- ❌ Stuffing every possible command into AGENTS.md +- ❌ Adding "hotfix" instructions for one-off behavior issues +- ❌ Instructions that aren't verifiable or enforceable +- ❌ Monolithic instruction files that rot over time +- ❌ Architecture decisions living in chat/docs outside repo + +## Sources +- OpenAI: https://openai.com/index/harness-engineering/ +- HumanLayer: https://www.humanlayer.dev/blog/writing-a-good-claude-md diff --git a/.pi/agent/settings.json b/.pi/agent/settings.json index e1683b0..68aa730 100644 --- a/.pi/agent/settings.json +++ b/.pi/agent/settings.json @@ -1,7 +1,7 @@ { - "lastChangelogVersion": "0.57.1", - "defaultProvider": "openai-codex", - "defaultModel": "gpt-5.4", + "lastChangelogVersion": "0.58.1", + "defaultProvider": "anthropic", + "defaultModel": "claude-opus-4-6", "defaultThinkingLevel": "high", "theme": "catppuccin-mocha" } \ No newline at end of file diff --git a/.pi/agent/skills/hf-cli/SKILL.md b/.pi/agent/skills/hf-cli/SKILL.md new file mode 100644 index 0000000..0ea2029 --- /dev/null +++ b/.pi/agent/skills/hf-cli/SKILL.md @@ -0,0 +1,158 @@ +--- +name: hf-cli +description: "Hugging Face Hub CLI (`hf`) for downloading, uploading, and managing repositories, models, datasets, and Spaces on the Hugging Face Hub. Replaces now deprecated `huggingface-cli` command." +--- + +Install: `curl -LsSf https://hf.co/cli/install.sh | bash -s`. + +The Hugging Face Hub CLI tool `hf` is available. IMPORTANT: The `hf` command replaces the deprecated `huggingface-cli` command. + +Use `hf --help` to view available functions. Note that auth commands are now all under `hf auth` e.g. `hf auth whoami`. + +Generated with `huggingface_hub v1.7.1`. Run `hf skills add --force` to regenerate. + +## Commands + +- `hf download REPO_ID` β€” Download files from the Hub. +- `hf env` β€” Print information about the environment. +- `hf sync` β€” Sync files between local directory and a bucket. +- `hf upload REPO_ID` β€” Upload a file or a folder to the Hub. Recommended for single-commit uploads. +- `hf upload-large-folder REPO_ID LOCAL_PATH` β€” Upload a large folder to the Hub. Recommended for resumable uploads. +- `hf version` β€” Print information about the hf version. + +### `hf auth` β€” Manage authentication (login, logout, etc.). + +- `hf auth list` β€” List all stored access tokens. +- `hf auth login` β€” Login using a token from huggingface.co/settings/tokens. +- `hf auth logout` β€” Logout from a specific token. +- `hf auth switch` β€” Switch between access tokens. +- `hf auth whoami` β€” Find out which huggingface.co account you are logged in as. + +### `hf buckets` β€” Commands to interact with buckets. + +- `hf buckets cp SRC` β€” Copy a single file to or from a bucket. +- `hf buckets create BUCKET_ID` β€” Create a new bucket. +- `hf buckets delete BUCKET_ID` β€” Delete a bucket. +- `hf buckets info BUCKET_ID` β€” Get info about a bucket. +- `hf buckets list` β€” List buckets or files in a bucket. +- `hf buckets move FROM_ID TO_ID` β€” Move (rename) a bucket to a new name or namespace. +- `hf buckets remove ARGUMENT` β€” Remove files from a bucket. +- `hf buckets sync` β€” Sync files between local directory and a bucket. + +### `hf cache` β€” Manage local cache directory. + +- `hf cache list` β€” List cached repositories or revisions. +- `hf cache prune` β€” Remove detached revisions from the cache. +- `hf cache rm TARGETS` β€” Remove cached repositories or revisions. +- `hf cache verify REPO_ID` β€” Verify checksums for a single repo revision from cache or a local directory. + +### `hf collections` β€” Interact with collections on the Hub. + +- `hf collections add-item COLLECTION_SLUG ITEM_ID ITEM_TYPE` β€” Add an item to a collection. +- `hf collections create TITLE` β€” Create a new collection on the Hub. +- `hf collections delete COLLECTION_SLUG` β€” Delete a collection from the Hub. +- `hf collections delete-item COLLECTION_SLUG ITEM_OBJECT_ID` β€” Delete an item from a collection. +- `hf collections info COLLECTION_SLUG` β€” Get info about a collection on the Hub. +- `hf collections list` β€” List collections on the Hub. +- `hf collections update COLLECTION_SLUG` β€” Update a collection's metadata on the Hub. +- `hf collections update-item COLLECTION_SLUG ITEM_OBJECT_ID` β€” Update an item in a collection. + +### `hf datasets` β€” Interact with datasets on the Hub. + +- `hf datasets info DATASET_ID` β€” Get info about a dataset on the Hub. +- `hf datasets list` β€” List datasets on the Hub. +- `hf datasets parquet DATASET_ID` β€” List parquet file URLs available for a dataset. +- `hf datasets sql SQL` β€” Execute a raw SQL query with DuckDB against dataset parquet URLs. + +### `hf discussions` β€” Manage discussions and pull requests on the Hub. + +- `hf discussions close REPO_ID NUM` β€” Close a discussion or pull request. +- `hf discussions comment REPO_ID NUM` β€” Comment on a discussion or pull request. +- `hf discussions create REPO_ID title` β€” Create a new discussion or pull request on a repo. +- `hf discussions diff REPO_ID NUM` β€” Show the diff of a pull request. +- `hf discussions info REPO_ID NUM` β€” Get info about a discussion or pull request. +- `hf discussions list REPO_ID` β€” List discussions and pull requests on a repo. +- `hf discussions merge REPO_ID NUM` β€” Merge a pull request. +- `hf discussions rename REPO_ID NUM NEW_TITLE` β€” Rename a discussion or pull request. +- `hf discussions reopen REPO_ID NUM` β€” Reopen a closed discussion or pull request. + +### `hf endpoints` β€” Manage Hugging Face Inference Endpoints. + +- `hf endpoints catalog` β€” Interact with the Inference Endpoints catalog. +- `hf endpoints delete NAME` β€” Delete an Inference Endpoint permanently. +- `hf endpoints deploy NAME repo framework accelerator instance_size instance_type region vendor` β€” Deploy an Inference Endpoint from a Hub repository. +- `hf endpoints describe NAME` β€” Get information about an existing endpoint. +- `hf endpoints list` β€” Lists all Inference Endpoints for the given namespace. +- `hf endpoints pause NAME` β€” Pause an Inference Endpoint. +- `hf endpoints resume NAME` β€” Resume an Inference Endpoint. +- `hf endpoints scale-to-zero NAME` β€” Scale an Inference Endpoint to zero. +- `hf endpoints update NAME` β€” Update an existing endpoint. + +### `hf extensions` β€” Manage hf CLI extensions. + +- `hf extensions exec NAME` β€” Execute an installed extension. +- `hf extensions install REPO_ID` β€” Install an extension from a public GitHub repository. +- `hf extensions list` β€” List installed extension commands. +- `hf extensions remove NAME` β€” Remove an installed extension. +- `hf extensions search` β€” Search extensions available on GitHub (tagged with 'hf-extension' topic). + +### `hf jobs` β€” Run and manage Jobs on the Hub. + +- `hf jobs cancel JOB_ID` β€” Cancel a Job +- `hf jobs hardware` β€” List available hardware options for Jobs +- `hf jobs inspect JOB_IDS` β€” Display detailed information on one or more Jobs +- `hf jobs logs JOB_ID` β€” Fetch the logs of a Job. +- `hf jobs ps` β€” List Jobs. +- `hf jobs run IMAGE COMMAND` β€” Run a Job. +- `hf jobs scheduled` β€” Create and manage scheduled Jobs on the Hub. +- `hf jobs stats` β€” Fetch the resource usage statistics and metrics of Jobs +- `hf jobs uv` β€” Run UV scripts (Python with inline dependencies) on HF infrastructure. + +### `hf models` β€” Interact with models on the Hub. + +- `hf models info MODEL_ID` β€” Get info about a model on the Hub. +- `hf models list` β€” List models on the Hub. + +### `hf papers` β€” Interact with papers on the Hub. + +- `hf papers list` β€” List daily papers on the Hub. + +### `hf repos` β€” Manage repos on the Hub. + +- `hf repos branch` β€” Manage branches for a repo on the Hub. +- `hf repos create REPO_ID` β€” Create a new repo on the Hub. +- `hf repos delete REPO_ID` β€” Delete a repo from the Hub. This is an irreversible operation. +- `hf repos delete-files REPO_ID PATTERNS` β€” Delete files from a repo on the Hub. +- `hf repos duplicate FROM_ID` β€” Duplicate a repo on the Hub (model, dataset, or Space). +- `hf repos move FROM_ID TO_ID` β€” Move a repository from a namespace to another namespace. +- `hf repos settings REPO_ID` β€” Update the settings of a repository. +- `hf repos tag` β€” Manage tags for a repo on the Hub. + +### `hf skills` β€” Manage skills for AI assistants. + +- `hf skills add` β€” Download a skill and install it for an AI assistant. +- `hf skills preview` β€” Print the generated SKILL.md to stdout. + +### `hf spaces` β€” Interact with spaces on the Hub. + +- `hf spaces dev-mode SPACE_ID` β€” Enable or disable dev mode on a Space. +- `hf spaces hot-reload SPACE_ID` β€” Hot-reload any Python file of a Space without a full rebuild + restart. +- `hf spaces info SPACE_ID` β€” Get info about a space on the Hub. +- `hf spaces list` β€” List spaces on the Hub. + +### `hf webhooks` β€” Manage webhooks on the Hub. + +- `hf webhooks create watch` β€” Create a new webhook. +- `hf webhooks delete WEBHOOK_ID` β€” Delete a webhook permanently. +- `hf webhooks disable WEBHOOK_ID` β€” Disable an active webhook. +- `hf webhooks enable WEBHOOK_ID` β€” Enable a disabled webhook. +- `hf webhooks info WEBHOOK_ID` β€” Show full details for a single webhook as JSON. +- `hf webhooks list` β€” List all webhooks for the current user. +- `hf webhooks update WEBHOOK_ID` β€” Update an existing webhook. Only provided options are changed. + +## Tips + +- Use `hf --help` for full options, usage, and real-world examples +- Use `--format json` for machine-readable output on list commands +- Use `-q` / `--quiet` to print only IDs +- Authenticate with `HF_TOKEN` env var (recommended) or with `--token` \ No newline at end of file