# commit

Adopt this skill: https://proskills.md/skills/other/clacky-ai-openclacky-clacky-skills-commit

Page: https://proskills.md/skills/other/clacky-ai-openclacky-clacky-skills-commit
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .clacky/skills/commit/SKILL.md
size: 13493
sha: 201d52dad17652c88999be263b77d4b3f4cc9567
upstream: https://github.com/clacky-ai/openclacky/blob/main/.clacky/skills/commit/SKILL.md

````text
---
---
name: commit
description: Smart Git commit helper that analyzes changes and creates semantic commits
user-invocable: true
disable-model-invocation: false
---

# Smart Commit Skill

This skill helps users create well-structured, semantic git commits by analyzing changes and suggesting appropriate commit messages.

## CRITICAL REQUIREMENT: SINGLE-LINE COMMITS ONLY

**ALL commit messages created by this skill MUST be single-line only.**

- DO: `git commit -m "feat: add user authentication"`
- DON'T: Multi-line commits with body text
- DON'T: Multiple `-m` flags
- DON'T: Commit messages with `\n` or additional paragraphs

Keep commits concise and focused. If more detail is needed, suggest adding it separately in PR descriptions or documentation.

## Overview

This skill automates the process of reviewing git changes and creating meaningful, conventional commits following the semantic commit format (feat/fix/chore/test).

## Core Philosophy

**THINK IN PURPOSES, NOT FILES**

This skill prioritizes understanding the OVERALL GOAL of changes before deciding how to commit them. The default approach is to:
1. Understand what the developer is trying to achieve
2. Group all related changes into meaningful, purpose-driven commits
3. Prefer fewer, cohesive commits over many fragmented ones

DO NOT commit file-by-file. DO NOT separate tests from implementation. DO NOT fragment features across multiple commits.

Instead, ask: "What story do these changes tell?" and commit accordingly.

## Usage

To use this skill, simply say:
- "Help me commit my changes"
- "Create semantic commits"
- "Review and commit changes"
- Use the command: `/commit`

## Process Steps

### 1. Analyze Git Status

First, check the current git status to understand:
- What files have been modified, added, or deleted
- Which files are staged vs unstaged
- Overall state of the working directory

```bash
git status
git diff --stat
```

### 2. HOLISTIC ANALYSIS - Understand the Overall Purpose

CRITICAL: Before diving into file-by-file analysis, step back and ask:

- What is the developer trying to achieve overall? (e.g., "Add authentication feature", "Fix login bugs", "Refactor database layer")
- Is there a common theme or goal across these changes?
- Can multiple changes be explained by a single higher-level purpose?

Think strategically, not tactically:
- BAD: "Changed auth.rb, changed user.rb, changed session.rb" -> 3 separate commits
- GOOD: "These are all part of implementing user authentication" -> 1 commit

Review ALL changes together first:
```bash
# Get overview of all changes
git diff --stat
git diff
```

Look for patterns:
- Do multiple files serve the same feature?
- Are there related bug fixes across files?
- Is there a refactoring that touches multiple files?
- Are tests accompanying their implementation?

### 3. Review Changes in Detail

Now examine each file to understand specifics:
- The nature of changes (new feature, bug fix, refactoring, tests, documentation)
- How it connects to the overall purpose identified in step 2
- Whether it's part of the main change or a separate concern

```bash
git diff <file>
```

### 4. INTELLIGENT GROUPING - Merge Similar Changes

CRITICAL PRINCIPLE: Prefer fewer, meaningful commits over many small commits

**Grouping Strategy:**

1. **Same Feature/Purpose = One Commit**
   - All files contributing to the same feature should be in ONE commit
   - Tests for a feature belong with the feature implementation
   - Related configuration changes belong with the feature

2. **Ask: "Would I explain these separately in a code review?"**
   - If you'd say "I added X, Y, and Z as part of feature F" -> ONE commit
   - If you'd say "I added X, and separately I fixed Y" -> TWO commits

3. **Look for these grouping opportunities:**
   - Feature + Tests: Always together
   - Implementation across multiple files: One commit if same feature
   - Bug fix + Test: Together if addressing same issue
   - Refactoring across modules: One commit if same refactoring goal
   - Documentation + Code: Together if documenting the same change
   - Configuration + Code: Together if config is required for the code

4. **Only split when:**
   - Changes serve genuinely different purposes
   - Mixing would make the commit unclear or too broad
   - One change is risky and should be isolated
   - Different semantic types that shouldn't mix (feat vs fix vs chore)

**Examples of Good Grouping:**

GOOD - Merged into ONE commit:
```
Commit: feat: add user authentication
  - lib/auth/authenticator.rb (new authentication logic)
  - lib/user.rb (user model updates)
  - lib/session.rb (session management)
  - spec/auth/authenticator_spec.rb (tests)
  - spec/user_spec.rb (updated tests)
  - config/routes.rb (auth routes)
```

GOOD - Different purposes, TWO commits:
```
Commit 1: feat: add user authentication
  - lib/auth/authenticator.rb
  - spec/auth/authenticator_spec.rb
  
Commit 2: fix: resolve database timeout issue
  - lib/database/connection.rb
  - spec/database/connection_spec.rb
```

BAD - Over-splitting, should be ONE commit:
```
Commit 1: feat: add authentication logic
  - lib/auth/authenticator.rb
  
Commit 2: feat: update user model for authentication
  - lib/user.rb
  
Commit 3: test: add authentication tests
  - spec/auth/authenticator_spec.rb
  
Commit 4: chore: add authentication routes
  - config/routes.rb
```

**Decision Tree:**
```
Are changes related to the same goal/feature/purpose?
|-- YES -> Combine into ONE commit
|   +-- Even if they touch different files/modules
+-- NO -> Keep as separate commits
    +-- Ask: Are they different semantic types (feat/fix/chore)?
        |-- YES -> Definitely separate
        +-- NO -> Consider if they could still be combined
```

### 5. Generate Commit Messages

Based on the holistic analysis, generate commit messages following the conventional commit format:

**Format**: `<type>: <description>`

**Types**:
- `feat`: New features or functionality
- `fix`: Bug fixes
- `chore`: Routine tasks, maintenance, dependencies
- `test`: Adding or modifying tests (only if standalone)
- `docs`: Documentation changes (only if standalone)
- `refactor`: Code refactoring without changing functionality
- `style`: Code style changes (formatting, whitespace)
- `perf`: Performance improvements

**CRITICAL GUIDELINES**:
- **MUST BE SINGLE-LINE**: Commit messages MUST be a single line only. DO NOT create multi-line commit messages.
- Keep messages concise (ideally under 50 characters)
- Use imperative mood ("add feature" not "added feature")
- Don't end with a period
- Be specific but brief
- **One logical PURPOSE per commit** (not one file per commit)
- Describe the overall goal, not implementation details
- If more detail is needed, suggest adding it in PR description or commit body separately, but the initial commit MUST be single-line

**Examples**:
- `feat: add user authentication` (not "add authenticator.rb, user.rb, session.rb")
- `fix: resolve login timeout issues` (not "fix auth.rb timeout")
- `chore: update dependencies` (not separate commits for each gem)
- `refactor: simplify database connection logic` (not one commit per file)
- `docs: update API documentation` (only if pure documentation change)

### 6. Execute Commits Immediately

No confirmation needed — analyze, group, and commit right away.

For each commit group:
```bash
# Stage specific files
git add <file1> <file2> ...

# Create commit with SINGLE-LINE message only
git commit -m "<type>: <description>"
```

**IMPORTANT**:
- Use ONLY `git commit -m "single line message"` format
- DO NOT use multi-line commits with additional body text
- DO NOT use `-m` flag multiple times
- Keep the commit message as a single, concise line

### 7. Final Summary

After all commits, show:
- Total number of commits created
- Each commit hash + message
- Suggest next steps (e.g., git push)

## Commands Used

```bash
# Check status
git status
git status --short

# View changes
git diff
git diff --stat
git diff <file>

# Stage files
git add <file>

# Create commit (SINGLE-LINE only)
git commit -m "type: single line description"

# NEVER use multi-line format like:
# git commit -m "title" -m "body"  -- DON'T DO THIS
# git commit -m "title\n\nbody"    -- DON'T DO THIS

# View commit history
git log --oneline -n 5
```

## Workflow Example

BAD Example (Over-splitting):
```
User: /commit

AI (WRONG APPROACH):
Found 5 modified files

Proposed commits:
  Commit 1: feat: add user model
    - lib/user.rb
  Commit 2: test: add user tests
    - spec/user_spec.rb
  Commit 3: fix: fix auth validation
    - lib/auth.rb
  Commit 4: test: add auth tests
    - spec/auth_spec.rb
  Commit 5: chore: update dependencies
    - Gemfile

Problem: Too fragmented! Tests separated from code.
```

GOOD Example (Holistic grouping):
```
User: /commit

AI (CORRECT APPROACH):
1. Analyzing all changes...
   Found 5 modified files

2. Identifying overall purpose...
   Main goal: Implementing user registration feature
   Secondary: Fixing existing auth bug
   Maintenance: Dependency updates

3. Holistic analysis:
   - lib/user.rb: New user registration feature
   - spec/user_spec.rb: Tests for user registration (same feature)
   - lib/auth.rb: Fix password validation bug (separate concern)
   - spec/auth_spec.rb: Tests for auth fix (same bug fix)
   - Gemfile: Updated dependencies (separate maintenance)

4. Proposed commits (grouped by purpose):

   Commit 1: feat: add user registration
     - lib/user.rb (implementation)
     - spec/user_spec.rb (tests)
     
     Reason: Feature and its tests belong together

   Commit 2: fix: correct password validation logic
     - lib/auth.rb (bug fix)
     - spec/auth_spec.rb (tests)
     
     Reason: Fix and its tests belong together

   Commit 3: chore: update gem dependencies
     - Gemfile
     
     Reason: Unrelated maintenance task

   Total: 3 meaningful commits instead of 5 fragmented ones

AI (executes immediately, no confirmation):
Commit 1 created (a1b2c3d): feat: add user registration
Commit 2 created (e4f5g6h): fix: correct password validation logic
Commit 3 created (i7j8k9l): chore: update gem dependencies

Summary: 3 commits created successfully!
Next steps: Review with 'git log' or push with 'git push'
```

## Best Practices

### Commit Message Rules
- **MUST be single-line only** - Never use multi-line commit messages
- Start with lowercase (except proper nouns)
- Use present tense imperative
- Be specific but concise
- Focus on "what" and "why", not "how"
- Maximum 72 characters for the single line

### Commit Organization - THINK PURPOSE, NOT FILES

**GOLDEN RULE: One logical PURPOSE per commit, not one FILE per commit**

### When to COMBINE Changes (Default Approach)
- **Feature implementation + its tests** (ALWAYS together)
- **Multiple files serving the same feature** (one commit)
- **Bug fix + its test** (ALWAYS together)
- **Code + required configuration** (together if config enables the code)
- **Refactoring across multiple files** (one commit if same refactoring goal)
- **Documentation + code it documents** (together if part of same change)
- **Related files in same module/feature** (one commit)

### When to SPLIT Commits (Exception Cases)
- **Truly different purposes**: e.g., "add feature X" vs "fix bug Y"
- **Different semantic types**: feat vs fix vs chore (usually)
- **Risky changes**: isolate if one change is experimental
- **Independent concerns**: changes that could be deployed separately
- **Too broad scope**: if one commit does too many unrelated things

### Anti-Patterns to Avoid
- NEVER split implementation and tests into separate commits
- NEVER create one commit per file unless files are truly independent
- NEVER split configuration from the code that requires it
- NEVER fragment a feature into multiple commits just because it touches multiple files

### Decision Framework
```
For each set of changes, ask:
1. "What was I trying to accomplish?" (identify the purpose)
2. "Do these files work together toward that purpose?" (YES -> combine)
3. "Would splitting these make the history harder to understand?" (YES -> combine)
4. "Could these changes be deployed independently?" (NO -> combine)
```

## Error Handling

- **No changes detected**: Inform user and exit gracefully
- **Merge conflicts**: Warn user to resolve conflicts first
- **Detached HEAD**: Alert user about repository state
- **Uncommitted changes during conflict**: Suggest stashing or committing
- **Empty commit message**: Request user input for clarification

## Safety Features

- Always review changes before committing (read diffs first)
- Execute commits immediately after analysis — no confirmation step
- Preserve git history integrity

## Integration with Workflow

This skill works best:
- After completing a feature or fix
- Before pushing to remote
- During code review preparation
- When cleaning up messy commit history (use with `git reset` first)

## Notes

- This skill does NOT push commits (user controls when to push)
- Follows conventional commits specification
- Encourages atomic, well-documented commits
- Helps maintain clean git history
- Useful for both beginners and experienced developers

## Dependencies

- Git installed and configured
- Working directory is a git repository
- User has permissions to commit
- Changes exist to commit

## Version History

- Created: 2025-02-01
- Purpose: Improve commit quality and development workflow
- Compatible with: Any git repository
````

## File: README.md
upstream: https://github.com/clacky-ai/openclacky/blob/main/README.md

````text
# OpenClacky

[![Build](https://img.shields.io/github/actions/workflow/status/clacky-ai/openclacky/main.yml?label=build&style=flat-square)](https://github.com/clacky-ai/openclacky/actions)
[![Release](https://img.shields.io/gem/v/openclacky?label=release&style=flat-square&color=blue)](https://rubygems.org/gems/openclacky)
[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1.0-red?style=flat-square)](https://www.ruby-lang.org)
[![Downloads](https://img.shields.io/gem/dt/openclacky?label=downloads&style=flat-square&color=brightgreen)](https://rubygems.org/gems/openclacky)
[![License](https://img.shields.io/badge/license-MIT-lightgrey?style=flat-square)](LICENSE.txt)

<p align="center">
  <a href="README.md">English</a> · <a href="README_CN.md">简体中文</a> · <a href="README_JA.md">日本語</a>
</p>

> Contributing? Read **[CONTRIBUTING.md](./CONTRIBUTING.md)** before opening a PR.

**The most Token-efficient open-source AI Agent.**

OpenClacky matches Claude Code on capability at comparable cost, and saves significantly against other open-source agents (~50% vs OpenClaw, costs only ~1/3 of Hermes). 100% open source (MIT), BYOK with any OpenAI-compatible model, built on two years of Agentic R&D and harness engineering.

> Website: https://www.openclacky.com/ · Backed by **MiraclePlus · ZhenFund · Sequoia China · Hillhouse Capital**

## Why OpenClacky?

Same task, how much do you pay? Under comparable agent workloads, OpenClacky saves a large amount of Token spend compared to mainstream alternatives.

| Agent | Relative cost | Notes |
|---|---|---|
| **OpenClacky** | **~0.8×** | 16 tools · ~100% cache hit · subagent routing |
| Claude Code | 1.0× (baseline) | World-class harness, closed-source subscription |
| OpenClaw | ~1.5× | Comparable harness agent |
| Hermes | ~3× | 52 built-in tools — schema bloat ~3–4× |

*Numbers are averages measured on internal common agent tasks, using Claude Code as the baseline. Full benchmark reports will be published on GitHub.*

## Feature comparison

Core agent capability is roughly on par across the field — the real differentiators are **cost, openness, Skill evolution, and integrations**.

| Feature | Claude Code | OpenClaw | Hermes | **OpenClacky** |
|---|:---:|:---:|:---:|:---:|
| Token cost | 1.0× | ~1.5× | ~3× | **~0.8** |
| Open source | ❌ Closed | ✅ Open | ✅ Open | ✅ MIT |
| BYOK / model freedom | ❌ Anthropic only | ✅ | ✅ | ✅ |
| Skill self-evolution | ❌ | ❌ | ✅ | ✅ |
| IM integration (Feishu/WeCom/WeChat/Discord/Telegram) | ❌ | ✅ | ✅ | ✅ |

## How we get the cost down

Not by cutting features — by compounding the right choice at every layer.

### 1. Ultra-high cache hit rate
Sessions never restart, double cache markers, **Insert-then-Compress** — the system prompt is never mutated, so compression still reuses the cache. **Measured cache hit rate: near 100%.**

### 2. Minimal tool set
Only **16 core tools**. Capabilities are offloaded to the Skill ecosystem via a single `invoke_skill` meta-tool. Tool count is not the metric — task completion rate is.

| OpenClacky | Claude Code | OpenClaw | Hermes |
|:--:|:--:|:--:|:--:|
| **16** | 40+ | 23 | 52 |

### 3. Idle-time auto-compression
Go to a meeting, grab coffee — the agent compresses long context in the background and pre-warms the cache. Your first message back hits the cache directly. **Cold-start first-token cost reduced by 50%+.**

### 4. BYOK — you pick the model, you set the cost
Any OpenAI-compatible API, plug and play. Official direct, aggregate routing, compatible relays — the choice is 100% yours. Use Claude for code, auto-route subtasks to DeepSeek, save another chunk of tokens.

Built on **2 years · 3 generations of agentic architecture · 6 core harness engineering decisions**.

## Skills — the soul of the agent

- **Invoke with `/`** — instant browse, fuzzy search, direct call. Hundreds of Skills at your fingertips.
- **Create Skills in natural language** — just describe what you want; the agent drafts `SKILL.md`, breaks down steps, and runs validation. No code required.
- **Self-evolving** — after each run, the agent updates the Skill based on execution context and results. The next call is more stable and more accurate.
- **Open & compatible** — supports Claude Skills / Markdown Pack / custom formats.
- **Monetizable** — polished Skills can be packaged for sale, with encrypted distribution, License management, and creator-defined pricing.

## Installation

### Desktop installer (recommended)

Double-click to install — environment, dependencies, and Skills all set up automatically.

- **macOS** — [Download `.dmg`](https://oss.1024code.com/openclacky-installer/official/openclacky-installer.dmg) (Apple Silicon / Intel)
- **Windows** — [Download `.exe`](https://oss.1024code.com/openclacky-installer/official/openclacky-installer.exe) (Windows 10 2004+ / Windows 11)

More options: https://www.openclacky.com/

### Command line

One-line install(Mac/Ubuntu):

```bash
/bin/bash -c "$(curl -sSL https://raw.githubusercontent.com/clacky-ai/openclacky/main/scripts/install.sh)"
```

Windows:

```bash
powershell -c "& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/clacky-ai/openclacky/main/scripts/install.ps1')))"
```

or using Ruby(3.x/4.x):

**Requirements:** Ruby >= 3.1.0

```bash
gem install openclacky
```

see more: https://www.openclacky.com/docs/installation

### Docker

#### Pre-built image (GHCR)

Images are published to GitHub Container Registry on version tags (`v*`).

```bash
# Replace <owner> with the repo owner (e.g. clacky-ai or your fork)
docker pull ghcr.io/<owner>/openclacky:latest
# or pin a release:
# docker pull ghcr.io/<owner>/openclacky:1.5.3
```

**Linux:**

```bash
docker run -d --name openclacky --network=host \
  -e CLACKY_ACCESS_KEY="" \
  -v openclacky-data:/root/.clacky \
  ghcr.io/<owner>/openclacky:latest
```

`--network=host` is required so the agent inside the container can reach Chrome's remote debugging port running on the host.

**macOS / Windows:**

```bash
docker run -d --name openclacky -p 7070:7070 \
  -e CLACKY_ACCESS_KEY="" \
  -v openclacky-data:/root/.clacky \
  ghcr.io/<owner>/openclacky:latest
```

> **Note:** On macOS/Windows, `--network=host` is not supported — browser automation may be limited.

Open **http://localhost:7070** after starting.

#### Build from source

```bash
git clone https://github.com/clacky-ai/openclacky.git
cd openclacky
# optional: set the OCI image version label
docker build --build-arg VERSION=1.5.3 -t openclacky .
docker run -d -p 7070:7070 -e CLACKY_ACCESS_KEY="" openclacky
```

Environment variables:

| Variable | Description |
|---|---|
| `CLACKY_ACCESS_KEY` | Protect the Web UI with an access key (empty = public mode; env must be present when binding `0.0.0.0`) |

## Quick Start

### Terminal (CLI)

```bash
openclacky            # start interactive agent in current directory
```

### Web UI

```bash
openclacky server     # default: http://localhost:7070
```

Open **http://localhost:7070** for a full chat interface with multi-session support — run coding, copywriting, research sessions in parallel.

Options:

```bash
openclacky server --port 8080        # custom port
openclacky server --host 0.0.0.0     # listen on all interfaces (remote access)
```

Linux sandbox hosts can opt into task limits with
`openclacky server --task-cgroup /sys/fs/cgroup/tasks`. The host must first create
that cgroup, configure its aggregate memory/CPU limits, and enable the `memory`
and `cpu` subtree controllers. Terminal shells and browser MCP daemons enter
child groups before exec; the server remains outside. Terminal results include
`resource_exhausted: "memory"` and an error when their group records an OOM kill,
even if the shell masks the child's failure. A separately managed Chrome must
also be placed under the same parent by its launcher. This option is off by
default and does not establish a security boundary against privileged commands.

## Configuration

```bash
$ openclacky
> /config
``
````
