pdum_agent_tools¶
This repository contains four Python packages being developed together in a uv workspace. The first local implementation is working, with real network/process tests and a live native-Codex-client interoperability check.
| Package | Intended purpose |
|---|---|
| habemus-papadum-mitm | A general-purpose MITM sidecar for traffic recording, independent of AI agents. |
| habemus-papadum-codex-launcher | Named Codex profiles and app-server launch configuration. |
| habemus-papadum-hostfork | Host-derived Linux environments, private storage, process ownership and recovery. |
| habemus-papadum-claude-launcher | Isolated Claude profiles and independent workers for official browser/Node SDK clients; new, unreleased package. |
Start with implementation status for commands, APIs, observed results and remaining limitations. The testing guide separates ordinary real local tests from explicitly enabled small paid provider probes. The profile setup guide covers Rich/Questionary interviews, selective native imports, editable TOML and upstream authentication workflows.
Architecture and implementation proposals¶
- Agreed design principles: trusted-network operation, practical hygiene, thin native configuration, foreground ownership, asynchronous inspection without initial capture quotas, and reusable Typer CLIs.
- Architecture overview
- Runtime contracts and gotchas: versioned behavior that client, coordinator and background-job implementations must account for.
- Codex launcher
- Codex client API design and implementation plan, with follow-up refinements from the HP Agent spikes
- Claude launcher, architecture, delivery plan, qualification report and checkpoint/follow-up
- MITM sidecar
- Hostfork, Linux environments with private storage and independent deadlines
- Hostfork architecture and implementation plan
- Hostfork compatibility and storage
- Joint implementation sequence
- Launcher implementation plan
- MITM implementation plan
- Research and spikes
- Codex client feasibility findings: combined results from spikes 025–034, before designing new client libraries.
- Agent orchestrator component map: the proposed multi-provider web application, with twenty-two component stubs and two throwaway web studies informing later specifications and live slices.
- HP Agent findings: browser/Node execution, SDK choice, faithful prompt records and implications for shared client/history code.
- HP Agent behavioral findings: host tools, skills/MCP, real compaction, model-selected delegation and a first coding comparison.
- HP Agent parallel work: parallel tools, independent jobs, client lifetimes and the AIUI integration contract.
- HP Agent power-user parity: source-linked feature inventory, shared runtime structure and advanced control edge cases.
The proposals recommend concrete architecture, interfaces, defaults, and phased acceptance criteria. They are broader than the first implementation, with remaining compatibility checks and deferred features distinguished from working functionality.
Start with the development guide for environment setup, conventions, validation, and releases. Repository instructions for coding agents are maintained in AGENTS.md, with CLAUDE.md pointing to the same guidance.