3.5.9 • Published 18h ago

@leejungkiin/awkit

Licence

MIT

Version

3.5.9

Deps

Vulns

Weekly

Summary Dependency Versions

AWKit — All-in-one Workflow Kit

AWKit Core · Single Source of Truth · Symphony-first · Context Pruning

AWKit is a professional AI-agent orchestration framework. This repository is the single source of truth for workflows, skills, core rules (core/GEMINI.md), and installation tooling.

Multi-Agent Symphony Model

AWKit operates through hierarchical collaboration. The Main Agent acts as the central Orchestrator while specialized Sub-agents execute narrow-scope tasks.

1. Symphony Flow

[User Request]
      │
      ▼
┌──────────────┐
│ Orchestrator │ (Gemini Flash)
│  (Triage)    │ Create sub-tasks in task.md
└──────┬───────┘
       ├─────────────────────────┐
       ▼                         ▼
┌──────────────┐          ┌──────────────┐
│   Designer   │ (Luna)   │  Reasoning   │ (Fable/Sol)
│ (UI Assets)  │ Mockups  │ (SystemPlan) │ implementation_plan.md
└──────┬───────┘          └──────┬───────┘
       │                         │
       └──────────┬──────────────┘
                  ▼
┌──────────────┐
│    Runner    │ (Qwen/Spark)
│ (Write Code) │ Edit file contents / Write logic
└──────┬───────┘
                  │
                  ▼
┌──────────────┐
│    Audit     │ (Fable/Sol)
│ (CodeReview) │ Lint check, run unit tests & commit
└──────────────┘

2. Logical Role Bindings

Roles are resolved dynamically based on priority lists in .project-identity or global configurations:

orchestrator: Central dispatcher and triage (Gemini 3.5 Flash via agy).
reasoning: System plans and structural reviews (Claude Fable via claude / GPT Sol via codex).
runner: File editing and coding tasks (Qwen Coder via qwen / Codex Spark via codex).
designer: Graphic designs, visual mockups, and spritesheets (GPT Luna via codex).
audit: Code review, type checks, and verification (Claude Fable / GPT Sol).

Setup & Installation

1. Global Package Installation

Install the AWKit CLI utility globally on your local environment:

Via HTTPS:

npm install -g @leejungkiin/awkit && awkit install

2. Initial Setup & Basic Usage (`awkit install`)

AWKit coordinates sync states between your local Project Directory (Source of Truth) and the active AI Runtime Directory (~/.gemini/antigravity-ide/) where the AI actually reads configurations.

To deploy all local rules, workflows, and templates from your project directory directly to the active AI runtime environment:

awkit install

Note: You must run awkit install whenever you modify configuration files or rules in your project workspace so that active AI agents can read the latest policies.

To deploy to all active platform profiles (Codex, Claude Code, Qwen, Cursor AI) at once:

awkit install --all

3. Overwriting & Force-Reinstalling

If you need to force-reinstall AWKit or overwrite current runtime files over older cached global scripts, run the global npm installer with the --force flag:

# Force reinstall the CLI utility globally
npm install -g @leejungkiin/awkit --force

# Or target a specific tagged release or commit hash
npm install -g @leejungkiin/awkit --force

# Re-link runtime directories after reinstallation
awkit install --all

4. Clean Uninstall

To completely remove the AWKit CLI and purge all local cached configurations, runtime profiles, and temporary drafts from your local system:

# 1) Uninstall the global CLI package
npm uninstall -g @leejungkiin/awkit
# or if installed via fork link alias
npm uninstall -g awkit

# 2) Purge local configuration registries and active model settings
rm -rf ~/.awkit

Beginner's Quickstart Guide

AWKit uses a bi-directional synchronization model to keep project codebases clean.

1. The Daily Workflow Loop

main-awf/ (Project Directory)  ── awkit install ──>  ~/.gemini/antigravity-ide/ (AI Runtime)
                               <── awkit harvest ──
                               <──  awkit sync   ──>

Golden Rule:
- Any edits to AI rules (core/GEMINI.md, AGENTS.md) or custom workflows must be done inside the Project Directory (main-awf/).
- After making changes, you must run awkit install to push them to the AI's active Runtime profiles.

2. Step-by-Step CLI Examples

Example 1: Verify Sync Status

Compare your local project codebase directories against the runtime profile to inspect file drifts:

awkit status

Purpose: Informs you if local changes are fully deployed to the AI runtime, or if the AI has edited files in the runtime that need harvesting.

Example 2: Initialize a New Project

Inject standard AWKit workspace files and skeletons into a newly initialized project:

awkit init

Purpose: Automatically bootstraps critical files such as .project-identity, CODEBASE.md, and default workspace templates.

Example 3: Deploy Changes to AI Runtime

Suppose you just updated some AI behavioral rules in core/GEMINI.md. Deploy them to the active runtime profile:

awkit install

Purpose: Installs the updated rules, symlinks skills, and registers templates for Codex, Claude Code, Qwen Code, and Cursor AI.

Example 4: Sync Changes Back (Harvest)

If the AI has created brainstorm drafts or modified files directly in its runtime directory, pull those changes back to the project repository:

awkit harvest

Purpose: Synchronizes runtime files back to the project root for safety checks and git commits.

Tip: Use awkit sync to execute both harvest and install in a single command.

Example 5: Gated Git Commit

Avoid calling git commit directly. Execute AWKit's automation gate to run syntax sanity checks and tests before committing:

awkit gate git auto "feat(docs): translate readme to english and update v13.0 specs"

Core Principles

AWKit enforces a set of non-negotiable principles to ensure safe and effective AI pairing:

Anti-sycophancy: AI must push back when an approach contains structural bugs; do not agree blindly.
Search Before Building (3-layer): Verify NeuralMemory/codebase first → then standard libraries/SDKs → only write new code as a last resort.
Completion Status Protocol: Label exits using DONE, DONE_WITH_CONCERNS, BLOCKED, or NEEDS_CONTEXT.
Decision Principles: Complete > Shortcuts, Evidence > Assumptions, Standard > Custom, Explicit > Implicit, Test > Trust, Small > Big.
3-Strike Escalation: Stop and report context to the developer if an issue persists after 3 unsuccessful bug-fixing attempts.
Scope Freeze for Debugging: Avoid refactoring unrelated systems while addressing bug fixes.
"Boil-the-lake" Verification Checklist: Verify error handling, boundary constraints, logging, and performance before exiting.
Safety Guardrails: Block dangerous commands by default; require developer authorization.

Context Compression Engine (CCE)

To prevent model amnesia, bugs, and API token waste, AWKit applies an advanced Context Compression Engine to optimize context sizes:

[Raw Chat History (60k tokens)] ────► [Caveman Compressor] ──► [Condensed History (3k tokens)]
                                                                               │
[Raw Source Code (400k tokens)] ────► [AST Signature Filter] ─► [Code Signatures (5k tokens)] ──► [Optimized Prompt]
                                                                               │
[System Guidelines] ────────────────► [RTK AST Compressor] ──► [Clean Rules (2k tokens)]

1. Token Compression Levels

RTK (Rust Token Killer): A built-in Rust AST pre-processor. It automatically cleans excess whitespaces, comments, formats brackets, and compresses JSON payloads before API requests, saving 20% - 30% of input tokens.
Caveman Mode: Triggered when chat histories exceed 50% of the model's context window. It condenses conversational logs, explanations, and warnings into strict technical bullet points, saving up to 75% of context.
ContextPack Isolation: Using flags with awkit exec:
- --no-context: Drops conversational history entirely, keeping prompt context clean.
- --files <path>: Instructs AWKit to extract only AST class signatures/definitions of the target file rather than loading raw text.
- --context-summary: Forces the compiler to summarize chat histories prior to invocation.

2. Memory Preservation

Spec Digest Boundary: Main Agents are forbidden from reading design specs, API documentation, or log files exceeding 200 lines directly. Loading large raw documents causes reasoning degradation.
- Mechanism: The Orchestrator delegates a light agent (Gemini Flash via agy) to read raw specs and output a compressed summary to scratch/digest-<spec>.md (< 80 lines). The Main Agent references only this digest.
Brain Artifact Cleanup: Session-specific plans and critiques are isolated in brain/<projectId>/ folders rather than cluttering workspaces, preventing file indexers from recurse-loading temporary drafts.

CLI Command Reference

Command	Description
`awkit env`	Inspect runtime environments, binary paths, and constitution bindings
`awkit doctor`	Scans system health (workflows, schemas, active configurations)
`awkit model list`	Lists registered models in the registry and their connectivity status
`awkit model ping <id>`	Tests response latencies for a specific model endpoint
`awkit config set <path> "<val>"`	Sets logical runner priorities, audio notifications, or proxy parameters
`awkit exec -m <model> -t <sec> "<dir>"`	Summons a dedicated sub-agent (supports ContextPack flags)
`awkit install`	Installs AWKit core runtime profiles to the active IDE profile
`awkit install --all`	Installs runtime profiles to all supported IDE profiles (Claude, Codex, etc.)
`awkit sync`	Runs full sync cycle: harvests runtime changes, then installs
`awkit status`	Compares the local repository against the installed runtime (drifts view)
`awkit harvest`	Pulls files from `~/.gemini/antigravity-ide/` back into this repository
`awkit gate git auto "<msg>"`	Performs verification gate checks, commits, and pushes changes

Repository Layout

main-awf/ (Source of Truth)
├── bin/                        # CLI entry points
├── core/                       # Core rules/routing for agents
├── workflows/                  # Workflow library
├── skills/                     # Source skill library
├── schemas/                    # JSON schemas
├── templates/                  # Project templates
├── scripts/                    # Tools, harvest and automation gates
└── package.json                # @leejungkiin/awkit

License

MIT

Troubleshooting: `npm warn allow-scripts`

If you encounter a warning like:

npm warn allow-scripts 21 packages have install scripts not yet covered by allowScripts
...
Run `npm approve-scripts --allow-scripts-pending` to review, or `npm approve-scripts <pkg>` to allow.

Why this happens

The project utilizes a security mechanism (such as allow-scripts or npm auto-run script blocking configurations) to protect your development environment from supply chain attacks. Third-party packages containing lifecycle scripts (such as preinstall, install, or postinstall scripts in packages like better-sqlite3, sharp, and tree-sitter) are temporarily blocked until you review and approve them.

Quick Fixes

You can quickly approve all trusted packages for the project by running the following loop in your Terminal:

for pkg in @ladybugdb/core @duytransipher/gitnexus @google/genai @leejungkiin/awkit-symphony better-sqlite3 onnxruntime-node protobufjs sharp tree-sitter tree-sitter-c tree-sitter-c-sharp tree-sitter-cpp tree-sitter-go tree-sitter-java tree-sitter-javascript tree-sitter-kotlin tree-sitter-php tree-sitter-python tree-sitter-ruby tree-sitter-rust tree-sitter-typescript; do npm approve-scripts $pkg; done

Keywords

awkit