npm package: @hunghg255/maicli
Description: CLI tool for dev teams to manage tasks and documentation
Author: hunghg255
Latest version: 0.0.3

<p align="center">
  <img src="images/cover.jpeg" alt="MAICLI - Task & Documentation Management" width="100%">
</p>

<h1 align="center">MAICLI</h1>

<p align="center">
  CLI-first knowledge layer that gives AI persistent memory of your project.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/maicli"><img src="https://img.shields.io/npm/v/maicli.svg?style=flat-square" alt="npm version"></a>
  <a href="https://www.npmjs.com/package/maicli"><img src="https://img.shields.io/npm/dm/maicli.svg?style=flat-square" alt="npm downloads"></a>
  <a href="https://github.com/hunghg255/maicli/actions"><img src="https://img.shields.io/github/actions/workflow/status/maicli-dev/maicli/ci.yml?branch=main&style=flat-square&label=CI" alt="CI"></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License: MIT"></a>
  <br>
  <a href="#"><img src="https://img.shields.io/node/v/maicli?style=flat-square" alt="node version"></a>
  <a href="#"><img src="https://img.shields.io/badge/TypeScript-5.0-blue?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript"></a>
  <a href="#"><img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey?style=flat-square" alt="platform"></a>
  <a href="https://github.com/hunghg255/maicli/stargazers"><img src="https://img.shields.io/github/stars/maicli-dev/maicli?style=flat-square" alt="GitHub stars"></a>
  <a href="#"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square" alt="PRs Welcome"></a>
</p>

---

> **TL;DR:** MAICLI is a CLI-first knowledge layer that lets AI reliably read and reuse your project context — instead of asking the same questions every session.

## The Problem

AI assistants are stateless — they forget your architecture, patterns, and decisions every session.

```
Session 1: "Implement feature X" → AI: "How does your auth work?" → You explain

Session 2: "Implement feature Y" → AI: "How does your auth work?" → You explain AGAIN

Session 100: Still explaining the same thing...
```

## The Solution

```bash
# Document once
maicli doc create "Auth Pattern" -d "JWT with guards" -f patterns

# Reference everywhere
maicli task create "Add login" -d "Follow @doc/patterns/auth-pattern"

# AI reads context automatically — never forgets
```

**How it works:**

1. **You plan** — Create tasks with acceptance criteria in Web UI or CLI
2. **You link** — Reference docs like `@doc/patterns/auth` in task descriptions
3. **AI executes** — Tell AI *"Work on task 42"*, it reads the task, follows the refs, and implements

MAICLI resolves `@doc/...` and `@task-...` into real files. AI reads them via [MCP](./docs/mcp-integration.md) or `--plain` output — no copy-paste needed.

## Install

```bash
# using npm
npm install -g maicli

# using bun
bun install -g maicli


maicli init
maicli browser  # Open Web UI
```

---

## Why MAICLI over Notion / Jira / Obsidian?

| | MAICLI | Notion/Jira | Obsidian |
|---|--------|-------------|----------|
| **AI-readable** | `--plain` output, MCP server | Copy-paste manually | Plugins needed |
| **File-based** | Git-friendly `.maicli/` folder | Cloud-locked | Local files |
| **CLI-first** | Full CLI + Web UI | Web only | GUI only |
| **Context linking** | `@doc/...` `@task-42` refs | Manual links | Wiki links |
| **Source of truth** | Local files (Git-versioned) | Remote database | Local vault |
| **Minimal setup** | `maicli init` and done | Complex setup | Many plugins |

**Best for:** Dev teams who pair with AI and want persistent project memory.

## Features

| Feature | Description |
|---------|-------------|
| **Task Management** | Create, track tasks with acceptance criteria |
| **Documentation** | Nested folders with markdown support |
| **Time Tracking** | Built-in timers and reports |
| **Context Linking** | `@task-42` and `@doc/patterns/auth` references |
| **AI Integration** | MCP Server for Claude, `--plain` output |
| **Web UI** | Kanban board, doc browser, dark mode |

---

## Quick Reference

```bash
# Tasks
maicli task create "Title" -d "Description" --ac "Criterion"
maicli task list --plain
maicli task <id> --plain                    # View task (shorthand)
maicli task edit <id> -s in-progress -a @me

# Documentation
maicli doc create "Title" -d "Description" -f "folder"
maicli doc "doc-name" --plain               # View doc (shorthand)

# Time & Search
maicli time start <id> && maicli time stop
maicli search "query" --plain
```

---

## Documentation

| Guide | Description |
|-------|-------------|
| [Command Reference](./docs/commands.md) | All CLI commands with examples |
| [Workflow Guide](./docs/workflow.md) | Task lifecycle from creation to completion |
| [Reference System](./docs/reference-system.md) | How `@doc/` and `@task-` linking works |
| [Web UI](./docs/web-ui.md) | Kanban board and document browser |
| [MCP Integration](./docs/mcp-integration.md) | Claude Desktop setup |
| [Configuration](./docs/configuration.md) | Project structure and options |
| [AI Workflow](./docs/ai-workflow.md) | Guide for AI agents |

---

## Roadmap

### Self-Hosted Team Sync 🚧 (Planned)

MAICLI will optionally support a self-hosted sync server — for teams that want shared visibility without giving up local-first workflows.

- **Real-time visibility** — See who is working on what
- **Shared knowledge** — Sync tasks and documentation across the team
- **Progress tracking** — Track activity over time
- **Full data control** — Self-hosted, no cloud dependency

The CLI and local `.maicli/` folder remain the source of truth.
The server acts only as a sync and visibility layer.

---

## Development

```bash
npm install
npm run dev      # Dev mode
npm run build    # Build
npm run test     # Test
```

## Links

- [npm](https://www.npmjs.com/package/maicli)
- [GitHub](https://github.com/hunghg255/maicli)
- [Changelog](./CHANGELOG.md)

For design principles and long-term direction, see [Philosophy](./PHILOSOPHY.md).

For technical details, see [Architecture](./ARCHITECTURE.md) and [Contributing](./CONTRIBUTING.md).

---