Open Source Project of the Day (Part 33): MyCodeAgent - A Claude Code-Style Code Agent Framework for Learning

A deep dive into MyCodeAgent, a code agent framework for learning and experimentation — focused on tool protocols, context engineering, sub-agents, and observability, making "what the Agent can do" and "why it can do it" traceable, verifiable, and extensible

·11 min read·AI Tools
Open SourceMyCodeAgentAI AgentClaude CodeFunction CallingPythonMCPTool ProtocolContext Engineering

Introduction

"Make both 'what the Agent can do' and 'why the Agent can do it' traceable, verifiable, and extensible."

This is Part 33 of the "Open Source Project of the Day" series. Today we explore MyCodeAgent (GitHub).

To deeply understand how a "Claude Code-style" code agent works — how the tool protocol is designed, how context is compressed, how sub-agents collaborate, how traces are written to disk — there's often a lack of an open-source sample that is readable, modifiable, and runnable. MyCodeAgent is exactly a code agent framework designed for learning and experimentation: using Function Calling for tool invocation (not relying on Action text parsing), using a unified tool response protocol and MCP for extensibility, using context engineering (truncation, compression, persistence) and Trace for observability, with Skills / Task sub-agents / AgentTeams mechanisms — making it easy to build a "traceable, verifiable, extensible" Agent lab locally.

Why it's worth checking out:

  • 📐 Systematic tool protocol: Unified response format (status/data/text/stats/context/error), Function Calling-driven, no natural language parsing dependency
  • 🧠 Context engineering: Layered injection, history compression, @file forced read, overflow writes to tool-output/
  • 🔧 Complete built-in tools: LS / Glob / Grep / Read / Write / Edit / MultiEdit / Bash / TodoWrite / Skill / Task / AskUser
  • 👥 AgentTeams (experimental): TeamCreate, SendMessage, Task persistent teammate, TeamFanout/TeamCollect parallel collaboration
  • 📊 Observability: JSONL + HTML dual-track Trace, sanitization, token statistics, tool call tree
  • 🔌 MCP extension: Connect external tools via mcp_servers.json
  • 🎓 Learning-friendly: Documentation covers protocol, context, truncation, Trace, Skill, Task, handoff notes

What You'll Learn

  • MyCodeAgent's positioning and use cases (learning function calling, context engineering, Skills/Task sub-agents)
  • Unified tool response protocol and Function Calling implementation
  • Context engineering: truncation, compression, persistence, @file and write-to-disk strategy
  • Skills directory conventions and SKILL.md format
  • Task sub-agent types and permission isolation
  • AgentTeams MVP: Team tools, Task three modes (oneshot / persistent / parallel)
  • Project structure, environment variables, CLI usage, and multi-model/multi-provider configuration
  • Comparison and reference with similar projects like OpenCode, HelloAgent

Prerequisites

  • Basic understanding of AI Agents and LLMs
  • Familiarity with Function Calling / Tool Use is beneficial
  • Local execution requires Python 3.8+, optionally configure Zhipu or other OpenAI API-compatible providers

Project Background

Project Introduction

MyCodeAgent's subtitle is "Claude Code like agent for study". It is a code agent framework for learning and experimentation, focused on four key areas:

  1. Tool protocol: How to define, call, and respond to tools so behavior is predictable and debuggable
  2. Context engineering: How to truncate, compress, and persist conversation and tool output to control tokens and cost
  3. Sub-agent mechanism: How Skills, Task sub-agents, and AgentTeams divide and collaborate on work
  4. Observability: How Trace, logs, and statistics make "what the Agent did, and why" traceable

The goal can be summarized as: Making "what the Agent can do" and "why the Agent can do it" traceable, verifiable, and extensible.

Target users:

  • Developers who want to learn how function calling and tool protocols work in real projects
  • Engineers or students researching context engineering (truncation, compression, persistence)
  • Agent developers who need to experiment with Skills / Task sub-agent collaboration
  • Learners who want to quickly set up an extensible local Agent lab

Author/Team Introduction

  • Repository: YYHDBL/MyCodeAgent (GitHub)
  • Acknowledgments: README credits Datawhale's HelloAgent, shareAI-lab's Kode-Cli, MiniMax-AI's Mini-Agent, anomalyco's opencode, and other open-source projects

Project Stats

  • ⭐ GitHub Stars: ~105
  • 🍴 Forks: ~22
  • 📦 Repository status: 79 commits, actively maintained
  • 📄 License: MIT (free to use and modify)
  • 📚 Documentation: Repository docs/ contains tool protocol, context engineering, truncation, Trace, Task, Skill, and handoff notes

Tech stack: Python 3.x, openai / pydantic / mcp / anyio, rich / prompt_toolkit.

Main Features

Core Purpose

MyCodeAgent's core purpose is to provide a readable, modifiable, and runnable "Claude Code-style" code agent implementation that lets you:

  1. Learn tool protocols: Function Calling-based invocation, unified response format (status/data/text/stats/context/error)
  2. Practice context engineering: Layered injection, history compression, @file forced read, overflow results written to tool-output/
  3. Experiment with sub-agents and collaboration: Skills, Task sub-agents, AgentTeams (Team + Task persistent/parallel)
  4. Observe behavior: Trace (JSONL + HTML), token statistics, tool call tree, session /save and /load

Making the transition from "being able to use Agents" to "being able to design, implement, and debug Agents."

Use Cases

  1. Learning Function Calling and tool protocols

    • See how tools are registered, called by LLMs, and how responses are parsed and displayed in a real project

  2. Studying context engineering

    • Experience truncation strategies, compression thresholds, @file injection, and long output write-to-disk — understand the impact on tokens and effectiveness

  3. Experimenting with Skills / Task sub-agents

    • Mount skills via SKILL.md, dispatch sub-agents (general/explore/plan/summary) via Task, observe main/lightweight model behavior and permission isolation

  4. Trying AgentTeams (experimental)

    • Create Teams, send messages, use Task's persistent/parallel modes for multi-role collaboration and parallel work

  5. Quickly building a local Agent lab

    • Switch models, switch providers (e.g., Zhipu), connect MCP, add Skills, iterate ideas quickly

Quick Start

Environment: Python 3.8+, pip.

# Clone
git clone https://github.com/YYHDBL/MyCodeAgent.git
cd MyCodeAgent
 
# Virtual environment (recommended)
python -m venv venv
source venv/bin/activate   # Linux/Mac
# .\venv\Scripts\activate  # Windows
 
# Dependencies
pip install -r requirements.txt

Configuration: Copy or create .env, configure for example:

# LLM
export OPENAI_API_KEY="your-api-key"
export DEFAULT_MODEL="gpt-4"
export TEMPERATURE="0.7"
 
# AgentTeams (optional, off by default)
export ENABLE_AGENT_TEAMS="true"
 
# Context
export CONTEXT_WINDOW="128000"
export COMPRESSION_THRESHOLD="0.8"

Run interactive CLI:

python scripts/chat_test_agent.py

Specify model and provider (e.g., Zhipu):

python scripts/chat_test_agent.py \
  --provider zhipu \
  --model GLM-4.7 \
  --api-key YOUR_API_KEY \
  --base-url https://open.bigmodel.cn/api/coding/paas/v4

View raw output for debugging:

python scripts/chat_test_agent.py --show-raw

Core Features

  1. Function Calling tool invocation

    • Does not rely on "Action text parsing"; directly uses the LLM's function/tool calling capability for more stable, traceable behavior

  2. Unified tool response protocol

    • Tools return a unified structure: status / data / text / stats / context / error, easy to parse, display, and log

  3. Built-in tools

    • LS / Glob / Grep / Read / Write / Edit / MultiEdit / Bash / TodoWrite / Skill / Task / AskUser, covering common file and execution needs

  4. AgentTeams MVP (experimental)

    • TeamCreate / SendMessage / TeamStatus / TeamDelete; Task supports oneshot, persistent (teammate), and parallel (fanout); TeamFanout / TeamCollect for parallel work distribution and result collection

  5. Context engineering

    • Layered injection, history compression, @file forced read; overflow tool output written to tool-output/ to avoid context overflow

  6. Lightweight circuit breaker

    • Tools that repeatedly fail are temporarily disabled to reduce pointless retries

  7. Trace tracking

    • JSONL + HTML dual-track logs, sanitization, optional raw responses — easy to reproduce and debug

  8. Session persistence

    • Supports /save and /load for long sessions and reproducibility

  9. MCP extension

    • Configure and connect external MCP tools via mcp_servers.json

  10. Enhanced CLI UI

    • Tool call tree, token statistics, progress display for improved readability

Project Advantages

ComparisonMyCodeAgentBlack-box Agent productsDemo-only projects
Tool protocolUnified response protocol + Function CallingOften internal implementationUsually no standard
Context engineeringTruncation/compression/write-to-disk/@file configurableOften not visibleSimple or missing
ObservabilityTrace JSONL/HTML, sanitization, statisticsLimited or noneOften just print
Sub-agents/collaborationSkills + Task + AgentTeamsProduct-dependentRarely present
DocumentationProtocol/context/truncation/Trace/Skill/Task, etc.Often just usage docsMinimal
PositioningLearning and experimentationProduction/productDemo-focused

Why choose MyCodeAgent?

  • Code and documentation are designed around "traceable, verifiable, extensible" — ideal for learning Agent internals
  • Tool protocol, context, and Trace have dedicated documentation, easy for secondary development and teaching
  • Built-in Skills / Task / AgentTeams for multi-role and collaboration experiments
  • MIT license, freely modifiable and integrable

Detailed Project Analysis

Architecture and Directory Structure

The structure overview from the README:

agents/           Main agent implementation
core/             Core runtime and context engineering
tools/            Tool system and registry
prompts/          System and tool prompts
docs/             Design and protocol documentation
scripts/          CLI entry (e.g., chat_test_agent.py)
tests/            Test suite
memory/           Trace and session output (local)
tool-output/      Long output write-to-disk directory
mcp_servers.json  MCP tool configuration
  • agents/: Main Agent scheduling, rounds, and tool invocation flow
  • core/: Context construction, compression, truncation, injection (including @file)
  • tools/: Tool registration, execution, unified response wrapping
  • prompts/: System prompts, tool descriptions, etc. that influence LLM behavior

Tool Protocol and Function Calling

  • Tools are exposed to the LLM via Function Calling, without parsing "Actions" from natural language
  • Tool returns follow a unified protocol including:
    • status: success/failure, etc.
    • data / text: structured or text results
    • stats / context: statistics or context information
    • error: error information

This enables:

  • Unified frontend/CLI display
  • Complete recording in Trace
  • Retry, circuit-breaking, and statistics support

Documentation entry: docs/tool_response_protocol.md.

Context Engineering

  • Layered injection: System prompt, tool descriptions, history messages organized in layers to control what enters the context
  • History compression: When history is too long, compress per strategy (e.g., summarize, truncate); related environment variables include CONTEXT_WINDOW, COMPRESSION_THRESHOLD, MIN_RETAIN_ROUNDS, SUMMARY_TIMEOUT
  • @file forced read: When user references via @file, ensure the corresponding content is added to context
  • Tool output truncation and write-to-disk: When a single tool output is too long, truncate (head/tail/head_tail), write overflow to tool-output/ to avoid filling the context

Documentation entries: docs/context_engineering.md, docs/tool_output_truncation.md.

Skills Mechanism

  • Convention directory: skills/<skill-name>/SKILL.md
  • Sample SKILL.md structure:
---
name: code-review
description: Review code quality and risks
---
# Code Review
 
Use this checklist:
- ...
 
$ARGUMENTS

$ARGUMENTS is replaced by the args passed to the Skill tool, injecting "skill description + parameters" into context together.

Documentation entry: docs/skill_tool_design.md.

Task Sub-agents (MVP)

  • Sub-agent types: general / explore / plan / summary, etc., for different complexity sub-tasks
  • Model selection: Main agent can use main/light models; sub-agents can be configured as lightweight models to save cost
  • Permission isolation: Sub-agents can be configured as read-only or with restricted tool sets for safety and control

Documentation entry: docs/task_subagent_design.md.

AgentTeams (Experimental)

  • Toggle: ENABLE_AGENT_TEAMS=true (off by default) for easy rollback
  • Team tools: TeamCreate / SendMessage / TeamStatus / TeamDelete
  • Parallel work distribution: TeamFanout / TeamCollect; Task mode=parallel with tasks list
  • Task modes:
    • oneshot: Single sub-task (default, backward compatible)
    • persistent: Create persistent teammate (team_name + teammate_name)
    • parallel: Dispatch multiple tasks at once (team_name + tasks)
  • Status: Message ACK (pending/delivered/processed), work item (queued/running/succeeded/failed/canceled)

Minimal example (triggered by main agent in interaction):

  1. TeamCreate(team_name="demo")
  2. Task(mode="persistent", team_name="demo", teammate_name="dev", ...)
  3. SendMessage(team_name="demo", from_member="lead", to_member="dev", text="...")
  4. TeamStatus(team_name="demo")
  5. TeamDelete(team_name="demo")

Quick rollback: Set ENABLE_AGENT_TEAMS to false or delete the environment variable.

Trace and Observability

  • Trace output: JSONL + HTML dual-track, optional sanitization, optional raw LLM responses
  • Environment variables: e.g., TRACE_ENABLED, TRACE_DIR, TRACE_SANITIZE, TRACE_HTML_INCLUDE_RAW_RESPONSE
  • Useful for reproducing issues and analyzing tokens and call chains

Documentation entry: docs/trace_logging_design.md.

MCP Integration

Configure mcp_servers.json in the project root to start MCP services via command, for example:

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "some-mcp-server", "--api-key", "${API_KEY}"]
    }
  }
}

This makes the tools provided by the MCP available in the Agent.

Key Environment Variables Summary

Main categories from the README:

  • Context / History: CONTEXT_WINDOW, COMPRESSION_THRESHOLD, MIN_RETAIN_ROUNDS, SUMMARY_TIMEOUT
  • Tool output truncation: TOOL_OUTPUT_MAX_LINES, TOOL_OUTPUT_MAX_BYTES, TOOL_OUTPUT_TRUNCATE_DIRECTION, TOOL_OUTPUT_HEAD_TAIL_LINES, TOOL_OUTPUT_DIR, TOOL_OUTPUT_RETENTION_DAYS
  • Skills: SKILLS_REFRESH_ON_CALL, SKILLS_PROMPT_CHAR_BUDGET
  • Subagent: SUBAGENT_MAX_STEPS, LIGHT_LLM_MODEL_ID / LIGHT_LLM_API_KEY / LIGHT_LLM_BASE_URL
  • AgentTeams: ENABLE_AGENT_TEAMS, AGENT_TEAMS_STORE_DIR, AGENT_TASKS_STORE_DIR
  • Trace: TRACE_ENABLED, TRACE_DIR, TRACE_SANITIZE, TRACE_HTML_INCLUDE_RAW_RESPONSE

Project Resources

Official Resources

  • 🌟 GitHub: https://github.com/YYHDBL/MyCodeAgent
  • 📚 Documentation: Repository docs/
    • Tool protocol: docs/tool_response_protocol.md
    • Context engineering: docs/context_engineering.md
    • Tool output truncation: docs/tool_output_truncation.md
    • Trace: docs/trace_logging_design.md
    • Task sub-agent: docs/task_subagent_design.md
    • Skill: docs/skill_tool_design.md
    • Handoff notes: docs/DEV_HANDOFF.md
  • 🐛 Issue Tracker: GitHub Issues

Reference Resources (README Acknowledgments)

  • Datawhale HelloAgent tutorial
  • shareAI-lab Kode-Cli
  • MiniMax-AI Mini-Agent
  • anomalyco opencode

Who Should Use This

  • Developers who want to learn Function Calling, tool protocols, context engineering, and Trace
  • Agent developers who need to experiment with Skills, Task sub-agents, and multi-role collaboration (AgentTeams)
  • Learners who want a readable, modifiable, runnable Claude Code-style reference implementation
  • Teams planning to build an extensible local Agent lab, connect MCP, and switch models/providers

Welcome to visit my personal homepage for more useful knowledge and interesting products

← Back to Blog