Metadata-Version: 2.4
Name: nodeskai
Version: 0.6.3
Summary: Stops your AI coding agent from guessing, over-engineering, and drifting outside scope. Built entirely on a phone.
License: MIT
Project-URL: Homepage, https://github.com/kaitokuroba2503/nodeskai
Project-URL: Repository, https://github.com/kaitokuroba2503/nodeskai
Project-URL: Issues, https://github.com/kaitokuroba2503/nodeskai/issues
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# NoDeskAI

*[Đọc bằng tiếng Việt](README.vi.md)*

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Made in Vietnam](https://img.shields.io/badge/made%20in-%F0%9F%87%BB%F0%9F%87%B3%20Vietnam-red.svg)](#)
[![Built on a phone](https://img.shields.io/badge/built%20on-%F0%9F%93%B1%20a%20phone-brightgreen.svg)](#)

**Your AI coding agent keeps guessing, over-engineering, and editing code
outside the scope you asked for. NoDeskAI fixes that — in one command.**

NoDeskAI is a skill-pack for AI coding agents (Claude Code, Cursor, Codex
CLI, Windsurf...): install it once and your agent stops silently guessing
at ambiguous requests, stops bloating simple tasks into over-engineered
solutions, and stops touching code outside what you asked for. It ships
with `audit` — a built-in scanner that checks the skill/rule files you're
about to trust for bloat, duplicate rules, and prompt-injection patterns.

> 🇻🇳 **Made in Vietnam.** Every line of this project — writing, testing,
> committing, and pushing to GitHub — was done entirely on an Android
> phone through Termux. No PC, no laptop, no iPad.

[![asciicast](https://asciinema.org/a/RGqjFoOOqW2pZR6G.svg)](https://asciinema.org/a/RGqjFoOOqW2pZR6G)

## Install

```bash
pip install nodeskai
```

## Usage

```bash
cd your-project
nodeskai init
```

This writes the full discipline ruleset into **all 4 agent-config files**
(`CLAUDE.md`, `.cursorrules`, `AGENTS.md`, `.windsurfrules`) — creating
whichever ones don't exist yet, and appending to any that already have
content of your own (your existing content is kept, NoDeskAI's block is
added below it). It also creates `NODESKAI.md` as the source of truth.
Every file gets a metadata line (flags + version) at the top so `sync`
knows how to update it later.

### Optional modes

```bash
nodeskai init --strict            # extra guardrails for high-risk decisions
nodeskai init --fast              # relaxed rules for obviously trivial tasks
nodeskai init --product-context   # adds a product/team-context skill (missing from the original CLAUDE.md)
```

`--strict` and `--fast` can't be combined (they're opposite modes).

### Update when a new skill version is available

```bash
nodeskai sync
```

Updates **every file NoDeskAI manages** (NODESKAI.md + installed
agent-configs) to match the currently installed NoDeskAI version, keeping
each file's own flags from `init` and preserving any hand-written content
that came before the NoDeskAI block. Files with no NoDeskAI metadata
(hand-written, never run through `init`) are reported as `[SKIP]` — they
don't break the command.

### Running `init` more than once

`init` is safe to re-run. Each time, `NODESKAI.md` is rebuilt fresh (a
`.bak` copy of the previous version is kept alongside it). Agent-config
files are **not** touched again once they already contain a NoDeskAI
block — you'll see `[SKIP]` for those; use `nodeskai sync` instead to
update them. Re-running `init` never duplicates content.

### Global flags (work on every command)

```bash
--path <dir>     # target project (default: current directory)
--quiet, -q      # only print errors/warnings, hide [OK]/[SKIP] lines
--dry-run        # preview what would change, write/delete nothing
--lang vi|en     # output language (default: vi, or env var NODESKAI_LANG)
```

`nodeskai --version` prints the installed version.

### A hard limit worth knowing

Everything above — `init`, `sync`, `audit` — is **advisory**. The rules
written into `CLAUDE.md`/`.cursorrules`/etc. are text the agent reads;
nothing forces it to comply, the same limit every prompt-based skill file
has (including the original CLAUDE.md). There is no way to make an LLM
follow markdown instructions the way a compiler enforces a type — that's
not a gap NoDeskAI (or any similar tool) can close.

### `nodeskai enforce` — the one thing that's actually enforced

```bash
nodeskai enforce
```

Installs a real Claude Code [PreToolUse hook](https://code.claude.com/docs/en/hooks)
that **blocks** (not just suggests against) a short list of destructive
bash commands (`rm -rf /`, `git push --force`, `git reset --hard`,
`chmod -R 777`, fork bombs) before they run — this is a process-level
gate, not a text suggestion.

**Scope, stated plainly:** this only covers Claude Code (the only tool
confirmed to have a real blocking hook), and only exact bash-command
patterns — not semantic rules like "don't guess" or "don't
over-engineer," which no tool can mechanically enforce. Known limitation
of Claude Code itself: a dispatched subagent can bypass the parent
session's hooks (a Claude Code limitation, not something this hook can
fix).

### Uninstall

```bash
nodeskai remove
```

Asks for confirmation before deleting anything (skip the prompt with
`--yes`; when run non-interactively — scripts, CI — it proceeds without
asking, same as before). Removes NoDeskAI from the project: deletes
`NODESKAI.md`, and strips the
NoDeskAI block out of each agent-config file. If a file was entirely
created by NoDeskAI (nothing written before the block), the whole file is
deleted; if you had hand-written content before the block, that content
is kept and only the NoDeskAI block is removed. A `.bak` copy of every
changed file is kept in case you need to restore it. Files with no
NoDeskAI metadata (never run through `init`) are left untouched.

### Check installed skill/agent-config files

```bash
nodeskai audit
```

Scans every skill/agent-config file in the project for:
- **Bloat** — files over 150 lines, where important rules risk getting
  buried.
- **Duplicate rules** — a sign of rules being added over time without ever
  being cleaned up.
- **Suspicious patterns** — prompt-injection attempts, destructive
  commands, data-exfiltration signs.

## Current status

v0.6.0 — full command set (`init`/`sync`/`audit`/`remove`/`enforce`),
`--dry-run`/`--quiet`/`--lang`/`--version` on every command, safe error
handling for non-UTF-8 files and write failures, and a real Claude Code
enforcement hook via `enforce` (the only part of NoDeskAI that isn't just
advisory).

## Support the project

If NoDeskAI is useful to you, you can support it through GitHub Sponsors
(link coming soon) or Ko-fi.

## License

MIT
