I've built some Features and Modifications

[Abdo-El-Mobayad]

Hey everone, I've built some modifications to Archon that I want to show here to anyone interested.
1st off I've been building my own Claude Code setup and started integrating it into Archon as soon as Cole launched it.

A few kew changes I carried out were deleting all the mcp tool descriptions and replacing them with my own archon-usage.md guide that explains both the mcp tools and how I want my Central Claude + SubAgents to use them. This was a great enhancement to overall efficiency and AI behaviour.

The 2nd was build my own Claude.MD for Archon. In my building, I've noticed that Claude Code is quite attached to it's ToDoWrite usage so instead of instructing it to forgo it for using Archon - I decided to have it synchronize it's ToDoWrite micro tasks to the archon task cards.

I used a strategy of dividing my worklow files into groups and appending them with an @mention into ClaudeMD and Subagent files. In the /doctor screenshot, you'll see my ClaudeMD has a very small token per Archon MCP Tool because I've built everything into the usage guide and other core files.

After that I did some changes / reductions to the fields, returned by mcp tool calls for Tasks and Docs to improve context efficiency. Get returns all fields, but List returns large fields excluded. (I did this because my setup produces alot of tasks with quite comprehensive descriptions.

Followed up with some UI changes to the Task Kanban to allow for better space efficiency and Epic/Sprint Tracking using the Feature field. (Also didn't want to change too much here to keep Archon's Tron Vibe as is)

Also changed how strict the assignee field on tasks is to allow my Central Claude to use it for spawning subagents.

Finally, I added a entire folder upload button so I can vectorize entire groups of markdown files / PDFs into a single Knowledge Source. (My setup builds alot of documentation and learnings as it goes along so it's helpful to RAG across that)

Let me know if/how you'd like me to formalize all this into a PR and I'll do so!

Built with Claudefa.st

Below here I'll put some commit summaries for more clarity.

🚀 Performance Optimizations (90-98% token reduction!)

MCP Tool Description Optimization

• Replaced verbose 60-150 line descriptions with concise 2-5 line summaries
• Results: 90-98% reduction in LLM token consumption
  • manage_project: 100+ lines → 4 lines (96% reduction)
  • manage_task: 140+ lines → 4 lines (97% reduction)
  • manage_document: 210+ lines → 5 lines (98% reduction)
  • manage_versions: 130+ lines → 5 lines (96% reduction)
• Files: project_module.py, rag_module.py

API Response Optimization

• Added exclude_large_fields parameter for 40-60% response size reduction
• Excludes unnecessary timestamps and metadata from MCP responses
• Files: task_service.py, document_service.py, projects_api.py

Backend Service Enhancements

• Improved error handling with structured logging
• Enhanced validation for assignee fields
• Added health check caching (30-second cache)
• Better resource utilization in MCP server
• Files: mcp_server.py, task_service.py, document_service.py

🎨 UI/UX Improvements

TaskBoardView Transformation

• Converted from vertical columns to horizontal collapsible rows
• Added proper status-specific colors and backgrounds:
  • Backlog: Gray theme (bg-gray-50)
  • In Progress: Blue theme (bg-blue-50)
  • Review: Purple theme (bg-purple-50)
  • Complete: Green theme (bg-green-50)
• Fixed uneven spacing between rows (consistent 1rem spacing)
• Better drag-and-drop visual feedback with green ring effect
• Files: TaskBoardView.tsx

Optimistic Updates Implementation

• Zero-latency drag-and-drop with immediate UI feedback
• Elegant rollback on server errors with state preservation
• User-friendly error messages with toast notifications
• Conflict resolution with timestamp tracking
• Files: TasksTab.tsx

Dynamic Assignee Field

• Removed hardcoded ASSIGNEE_OPTIONS constant
• Dynamic dropdown populated from existing task assignees
• Flexible string type allowing custom assignee values
• Maintains backward compatibility with default assignees
• Files: EditTaskModal.tsx, project.ts

📊 Impact Summary

• LLM Performance: 90-98% token reduction for MCP interactions
• API Efficiency: 40-60% smaller response payloads
• UI Responsiveness: Zero-latency interactions with optimistic updates
• Flexibility: Dynamic assignees support any workflow
• Visual Design: Color-coded status rows for better task management

---

🎨 Visual Feature Grouping

• Implemented two-level hierarchy: Status rows → Feature sub-rows
• Each feature group displays with colored left borders (8 rotating colors)
• Feature labels show name and task count
• Semi-transparent backgrounds for visual separation
• Alphabetical sorting of features for consistency

🔄 Drag-and-Drop Between Features

• Added drop zones for each feature group
• Visual feedback: Purple ring highlight when hovering over target feature
• Optimistic updates for instant UI response (same pattern as status moves)
• Automatic rollback on API failure with error notifications
• Database persistence of feature changes

📁 Collapse/Expand Functionality

• Status level: Collapse/expand ALL feature groups at once (⏶/⏷ buttons)
• Feature level: Individual feature group collapse/expand (▶/▼ buttons)
• Maintains collapsed state during session
• Tasks hidden when collapsed, labels remain visible

🎨 UI/UX Improvements

• Fixed dark mode scrollbar styling (no more white backgrounds)
• Custom scrollbar colors for both light and dark modes
• Horizontal scrolling for feature rows (overflow-x-auto)
• Vertical scrolling for status sections (max-height: 600px)
• Increased max-height to accommodate multiple feature sub-rows

🚀 Performance Optimizations

• UseMemo for feature grouping calculations
• UseCallback for event handlers
• Optimistic updates for instant feedback
• Efficient re-rendering with proper React keys

🔧 Technical Implementation

• Fixed TypeScript type annotations (Record<string, Task[]>)
• Fixed index calculation for drag-and-drop operations
• Defensive programming in hash function for color selection
• Error handling with automatic rollback on failures

This creates much better visual organization for projects with multiple features
or workstreams, making it easier to see related tasks at a glance while
maintaining smooth drag-and-drop functionality between both statuses and features.

• Add folder upload UI as third option alongside URL and file upload
• Support drag & drop of entire folders with automatic file filtering
• Create single source_id for entire folder (folder_[name]_[timestamp])
• Implement smooth sequential progress bars that stay at 100% once completed
• Add dynamic icon display based on source type (folder/file/url)
• Fix database cleanup to properly delete from archon_project_sources table
• Fix source_type metadata handling for correct icon display
• Support up to 100 files per folder with 10MB total size limit
• Add validation for supported file extensions (code, docs, config files)
• Ensure fluid progress animation matching single file upload behavior

Technical improvements:

• Frontend: Add percentage-based progress for folder uploads
• Backend: Implement staged progress updates for first file vs subsequent files
• Fix Python syntax error in exception handling
• Add smooth animations with small delays for better UX

---

[SimpleMortikizer]

super rad

[coleam00]

Awesome @Abdo-El-Mobayad, I love how much effort you've put into making Archon perfect for your use cases! I would more than welcome PRs for these things. I'll leave it up to you on how to split this up, but my big ask is that you can each PR as granular as possible. As in every change you have here that could be considered its own isolated feature would make a good PR!

[Krashnicov]

@Abdo-El-Mobayad these are great, I was looking at doing something very very similar, particularly around the tool descriptions and duplication we get from CLAUDE-ARCHON, etc etc.

Putting the information in to files / prompts and only referencing them when needed is way more efficient, bravo.

Let me know if you want to collaborate, I'm not a coder but the optimisations here, especially of prompts and context, is right in my wheelhouse.

[Abdo-El-Mobayad]

Hey @Krashnicov Thanks! Sure thing I'm open to your suggestions on how to go about that.
Structuring prompts, context and operational directives across multi agent systems is also one of my favorite things.
I've made some big discoveries yesterday with Claude Code 1.0.86 releasing the /context option and I'm rethinking my approach.
Let me know your thoughts!

[Krashnicov]

Quite, I saw that - and was playing with verbose logging output and async claude invocations / sdk / cli also. A lot of good information on the order of things using those tools.

[Krashnicov]

Are you in the community, @Abdo-El-Mobayad ? My preference is chat / discord if you're open to it.

[Abdo-El-Mobayad]

Btw everyone
Further Reason to Reduce MCP tool Descriptions in Archon!!!

My MCP Tool Context went from 60-70 per tool to 500+

[Abdo-El-Mobayad]

CC Conversation Snippet

● Sure! Here's exactly what's loaded in my context for one of your MCP tools. I'll show you manage_task
since it's one of the larger ones at 841 tokens:

{
"description": "Task management with status workflow: todo → doing → review → done.\n\nActions:
create, list, get, update, delete, archive.\nFilter by status, project, or assignee.\n",
"name": "mcp__archon__manage_task",
"parameters": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"action": {
"title": "Action",
"type": "string"
},
"assignee": {
"default": "User",
"title": "Assignee",
"type": "string"
},
"code_examples": {
"default": null,
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Code Examples",
"type": "array"
},
"description": {
"default": "",
"title": "Description",
"type": "string"
},
"feature": {
"default": null,
"title": "Feature",
"type": "string"
},
"filter_by": {
"default": null,
"title": "Filter By",
"type": "string"
},
"filter_value": {
"default": null,
"title": "Filter Value",
"type": "string"
},
"include_closed": {
"default": false,
"title": "Include Closed",
"type": "boolean"
},
"page": {
"default": 1,
"title": "Page",
"type": "integer"
},
"per_page": {
"default": 50,
"title": "Per Page",
"type": "integer"
},
"project_id": {
"default": null,
"title": "Project Id",
"type": "string"
},
"sources": {
"default": null,
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Sources",
"type": "array"
},
"task_id": {
"default": null,
"title": "Task Id",
"type": "string"
},
"task_order": {
"default": 0,
"title": "Task Order",
"type": "integer"
},
"title": {
"default": null,
"title": "Title",
"type": "string"
},
"update_fields": {
"additionalProperties": true,
"default": null,
"title": "Update Fields",
"type": "object"
}
},
"required": ["action"],
"title": "manage_taskArguments",
"type": "object"
}
}

And here's a simpler one, health_check at 404 tokens:

{
"description": "\n Perform a health check on the MCP server and its dependencies.\n\n Returns:\n
JSON string with current health status\n ",
"name": "mcp__archon__health_check",
"parameters": {
"properties": {},
"title": "health_checkArguments",
"type": "object"
}
}

As you can see, even the simple health_check with no parameters still includes the full JSON Schema
structure. The token count includes:

• The function name with prefix
• The full multiline description
• The complete JSON Schema with all the boilerplate
• All parameter definitions with types, titles, defaults
• The required array
• All the JSON syntax overhead

This is why your tools went from ~60-70 tokens (just a simple description) to 400-800+ tokens (full
schema definition).

[crisap94]

@Abdo-El-Mobayad Do yo u have this ofrk uploaded somewhere? I'd like to have a look, I'm deeply interested in your approach, and furthermore, i'd like to contribute to split this into readable PRs for the Main Archon branch.

[Abdo-El-Mobayad]

Yes @crisap94 Thank you very much I'd appreciate someone else being responsible for preparing the PRs

Here you go it's all here
https://github.com/Abdo-El-Mobayad/Archon/tree/feature/claude-fast-integration

You won't be able to find use my own .claude config though as that's private on Claudefa.st but the Archon modifications are all there

[Javierg9n4]

Hey @Abdo-El-Mobayad, this is awesome! I'm gonna try it out ASAP.

Quick question: in that last screenshot with the Claude code and sub-agents, are those yours, or are they part of Archon? If they're yours, how do you get them all to work well with Archon?

I'm having trouble with my sub-agents in Claude code and opencode – the main agent keeps forgetting to use them.

I figure it's something in my CLAUDE.md or the workflow, but I can't figure it out.

Do you have a custom workflow, or are you just using the one Archon has?

Any tips or examples would be super helpful! Thanks!

[Abdo-El-Mobayad]

I started building my own workflow @ https://claudefa.st a few weeks before Archon launched.
Learned alot about how Claude Code works & Sub Agent tool calls & context windows n all that.
Even asked Anthropic's CC Team on Twitter a few questions. They reply regularly.

When Archon launched I knew exactly how I wanted to modify it.
I had Claude analyze Archon + my framework and co plan a migration / framework upgrade. It was faster that I thought.
The result of that is what you see above.

One of the key breakthroughs was syncing ToDoWrite to Archon Tasks instead of trying to kill that behaviour. Claude itself suggested that back in v1 of ClaudeFast. It's quite attached to its ToDoWrite.

Anyway I'm releasing v3 (which is a pure Archon variant) on claudefa.st this weekend.

I can look at your setup if you want and offer some thoughts.

[Abdo-El-Mobayad]

@Javierg9n4
Can you message me on twitter please?

[Javierg9n4]

@Javierg9n4
Can you message me on twitter please?

Done

[Wirasm]

It seems like you are building some really cool things here @Abdo-El-Mobayad
I will move this to discussions for now, feel free to contribute to Archon and open PR's if you have some ideas of how to integrate these flows while still remaining flexible

Great stuff!