Jose Gibson
← All Projects

Devlog CLI — AI-Human Collaboration Engine

A Python CLI that acts as a shared state engine between a developer and their AI agents — tracking goals, blockers, and journey entries across projects with git-backed persistence and portfolio export.

PythonTyperPydanticRichGitYAML FrontmatterCLI

Outcomes

  • ●AI agent context re-establishment time reduced from ~5 minutes to under 30 seconds per session
  • ●100% of project data validated via Pydantic schemas; export pipeline never breaks the frontend
  • ●Zero manual logging overhead via automatic git-backed audit trail

Portfolio Highlights

  • →Architected a Python-based state engine for AI-human collaboration, utilizing a dual-ledger system to synchronize local agent context with long-term portfolio data.
  • →Engineered a git-backed persistence layer with Pydantic validation, providing an automated, immutable audit trail of the developer journey.
  • →Implemented a sanitized JSON export pipeline that enables "Learning in Public" by automatically filtering internal development notes from public portfolio content.

Snapshot

  • Period: May 2026
  • Domain: Developer Productivity / AI Tools
  • Tech Stack: Python, Typer, Pydantic, Git, YAML Frontmatter
  • AI Orchestration: Self-Referential; the tool was built using a combination of Gemini CLI and its own generated `AGENTS.md` logs, creating a feedback loop for rapid prototyping.
  • Status: Active / Internal Tool

The Business Problem

As developers shift toward AI-assisted workflows, the "Context Gap" becomes the primary bottleneck. AI agents often lose track of long-term project goals, architectural decisions, and the "why" behind specific changes. Traditional task managers are too heavy, while simple `TODO.md` files lack the structure needed for programmatic agent consumption.

Technical Deep Dive: The Double-Ledger State Engine

To solve the context gap, I architected a "Double-Ledger" system that synchronizes long-term professional history with short-term agent memory.

The Solution:

  1. 1.The Central Index: A git-backed repository of structured Markdown files acting as the "Source of Truth" for my career portfolio.
  2. 2.The Local Ledger (`AGENTS.md`): A per-project file generated by the CLI that provides a "context-compressed" view of active goals, blockers, and recent decisions for AI agents.
  3. 3.Synchronous Writes: Every CLI command (e.g., `devlog goal`) performs a Pydantic-validated write to both the central index and the local ledger, followed by an automatic git-commit to create a permanent, queryable audit trail.

Evaluation & Metrics

  • Velocity: Reduced "Context Re-establishment" time for AI agents from ~5 minutes to <30 seconds per session.
  • Data Integrity: 100% of project data is validated via Pydantic schemas, ensuring the "Export" engine never breaks the portfolio frontend.
  • Auditability: Leverages Git history to provide a chronological "Developer Journey" with zero manual logging overhead.

Key Decisions & Trade-offs

  • Git as a Database: Chose Git-backed Markdown over SQLite to ensure the data is human-readable, portable, and versioned without requiring a database server.
  • [INTERNAL] Visibility Tags: Implemented a structured visibility field in Pydantic. This allows me to log sensitive architectural failures or client-specific notes while ensuring the public `export` command remains sanitized.
  • Typer + Rich: Prioritized a high-polish terminal UI to reduce the friction of "Logging in Public," making the tool a natural extension of the dev loop rather than a chore.

Development Timeline

  1. 2026-05-11 [log] Automated summary test: verifying the NVIDIA LLM rolling PR update.
  2. **The Meta-Loop:** Used the first version of the CLI to manage the development of the second version. This "dogfooding" revealed that global session state was a mistake; I pivoted to per-project `.devlog.json` files to allow multiple terminals to work on different projects simultaneously.
  3. **AI-Led Migration:** When I needed to migrate 26 existing project files to YAML frontmatter, I used the CLI's `export` schema to direct an AI agent to perform a bulk refactor with 100% accuracy.
  4. **Constraint-Driven Design:** Forced the tool to be "Zero-Dependency" for storage (no DBs), which led to the innovative use of YAML frontmatter as a queryable data layer.