Feature: AI-Powered Command Descriptions

[adithya-naik]

Overview

Currently, CMD Tracker stores commands along with their execution timestamp.

Example:

{
  "command": "git status",
  "time": "2026-06-01T15:56:17.515Z"
}

This feature proposes enriching each command with an AI-generated description that explains what the command does.

Example:

{
  "command": "git status",
  "time": "2026-06-01T15:56:17.515Z",
  "description": "Shows the current state of the Git repository, including modified, staged, and untracked files."
}

---

Motivation

Many users repeatedly execute commands without fully understanding their purpose.

By storing AI-generated explanations alongside tracked commands, CMD Tracker can evolve from a command tracker into a command learning platform.

Benefits:

• Learn commands while using them
• Build a personal command knowledge base
• Improve command discoverability
• Enable future learning-focused features

---

Proposed Implementation

Current Structure

{
  "git": [
    {
      "command": "git status",
      "time": "2026-06-01T15:56:17.515Z"
    }
  ]
}

New Structure

{
  "git": [
    {
      "command": "git status",
      "time": "2026-06-01T15:56:17.515Z",
      "description": "Shows the current state of the Git repository, including modified, staged, and untracked files."
    }
  ]
}

---

Command Normalization

Before sending a command to the AI model, dynamic values should be generalized.

Examples

Input

git commit -m "add : engines in package.json"

Normalized

git commit -m "<message>"

---

Input

git checkout feature/login

Normalized

git checkout <branch>

---

Input

npm install express

Normalized

npm install <package>

This helps generate reusable and higher-quality descriptions.

---

Workflow

User runs command
       ↓
tracker save
       ↓
categorize command
       ↓
normalize command
       ↓
generate description using AI
       ↓
store:
{
  command,
  time,
  description
}
       ↓
write to common.json

---

Example Output

{
  "git": [
    {
      "command": "git --version",
      "time": "2026-06-01T15:54:56.060Z",
      "description": "Displays the installed Git version."
    },
    {
      "command": "git status",
      "time": "2026-06-01T15:56:17.515Z",
      "description": "Shows the current state of the Git repository."
    },
    {
      "command": "git remote -v",
      "time": "2026-06-01T15:57:29.912Z",
      "description": "Lists configured remote repositories with their fetch and push URLs."
    }
  ]
}

---

Future Possibilities

This feature unlocks several future enhancements:

Learning Mode

tracker learn

Review previously used commands and their explanations.

Command Search

Search commands by description instead of exact command text.

AI Summaries

Generate insights such as:

"You frequently use Git branching commands but rarely use Git rebase commands."

Export Cheat Sheets

Generate personalized command reference documents from tracked history.

---

Considerations

• Description generation should be optional and configurable.
• Descriptions should be cached after generation.
• Existing users should remain compatible with older data structures.
• AI failures should not block command tracking.
• Sensitive user-specific values should be normalized before being sent to the AI model.

---

Acceptance Criteria

• Add a description field to tracked command objects.
• Normalize commands before generating descriptions.
• Generate concise command explanations using AI.
• Persist descriptions in common.json.
• Preserve existing tracking functionality.
• Gracefully handle AI service failures.