===============================================================================
GARLIC-AGENT
FULL ASCII SYSTEM MAP
CURRENT VIEW BASED ON THE PASTED archall
0. ONE LINE IDENTITY
garlic-agent is not just "a chatbot".
It is a phone based Termux operating environment that combines:
1) a chat brain
2) a tool executor
3) a safety and rollback kernel
4) a Korean friendly script engine
5) a local knowledge system
6) a versioned patch workflow
7) background daemons
8) a measurement and verification culture
So the real shape is this:
user
-> web ui
-> agent brain
-> security wall
-> tool executor
-> file/db/runtime effects
-> gvcs verification and rollback
-> measured closeout
That is why it feels more like an "AI operating environment"
than a single model wrapper.
1. THE WHOLE SYSTEM IN ONE BIG PICTURE
+----------------------------------+
| HUMAN USER |
| phone browser on localhost |
+----------------+-----------------+
|
v
+----------------------------------------------------------------------------------+
| WEB ENTRY LAYER |
|----------------------------------------------------------------------------------|
| web.py : tiny shim |
| web_server.py : main web server |
| web_auth.py : token check |
| web_routes_chat.py : chat route |
| web_routes_docs.py : docs route |
| web_routes_admin.py : admin route |
| web_routes_gl.py : GarlicLang route |
| web_routes_hud.py : HUD route |
| web_routes_gvcs.py : GVCS route |
| garlic_talk.py : two-AI talk helper |
| search_web.py : web search endpoint |
| typo_guard.py : typo correction guard |
+-----------------------------------+----------------------------------------------+
|
| user message
v
+----------------------------------------------------------------------------------+
| BRAIN / ORCHESTRATION |
|----------------------------------------------------------------------------------|
| agent.py |
| |
| internal order |
| 1. read rules |
| 2. read tool contracts |
| 3. attach history |
| 4. attach RAG |
| 5. call provider |
| 6. parse response |
| 7. parse tools |
| 8. execute or answer |
| |
| nearby helpers |
| execution_router.py : parse tools and dispatch |
| anchor_manager.py : anchor save/restore |
| pre_tools.py : pre tool detection |
| pre_tools_extract.py : md/json extraction |
| pre_tools_normalize.py : normalize file names/keys |
| pre_tools_plan.py : decompose compound natural language tasks |
| session_manager.py : session state |
| number_freeze.py : numeric hallucination guard |
| fact_ledger.py : immutable execution records |
| skills/skill_loader.py : direct skill matching and GL-DIRECT |
+---------------------------+--------------------------------------+---------------+
| |
| tool/api intent | model call
v v
+-------------------------------+ +-----------------------------------+
| SECURITY WALL | | LLM PROVIDERS |
|-------------------------------| |-----------------------------------|
| security.py | | provider_adapter.py |
| - blocked commands | | response_sanitizer.py |
| - allowed dirs | | shared_stop_flag.py |
| - key masking / patterns | | |
| | | remote: Gemini / DeepSeek / |
| | | MiniMax / Groq / |
| | | NVIDIA / Cerebras |
| | | local : Local-Gemma / gemma_cpp |
+---------------+---------------+ +----------------+------------------+
| |
+------------------+---------------------+
|
v
+----------------------------------------------------------------------------------+
| TOOL EXECUTION |
|----------------------------------------------------------------------------------|
| tools.py |
| read | write | exec | patch | search | snapshot_list | restore | app | screen |
| gvcs | inspect |
| |
| garliclang_bridge.py : bridge to GarlicLang interpreter |
| search.py : FTS5 + vector hybrid search |
| snapshots_db.py : snapshot DB wrapper |
+-----------------------------------+----------------------------------------------+
|
+-------------------+-------------------+--------------------------+
| | |
v v v
+------------------------------+ +----------------------------------+ +------------------+
| FILE SYSTEM | | DATABASES | | GL ENGINE |
|------------------------------| |----------------------------------| |------------------|
| source files | | knowledge.db | | interpreter.py |
| docs | | snapshots.db | | parser.py |
| configs | | chat_sessions.db | | lexer.py |
| generated patches/logs | | pending patch metadata | | ast_nodes.py |
| backups and anchors | | | | line_parser.py |
+------------------------------+ +----------------------------------+ | lang_map_ko.py |
| lang_map_en.py |
+---------+--------+
|
v
+----------------------+
| GL script execution |
| Korean command map |
| repeat / verify / |
| checkpoint / report |
+----------------------+
2. THE REAL THREE AXES
The cleanest mental model is not "many files".
It is "three central axes".
+-------------------------------------------+
| AXIS 1 : BRAIN |
|-------------------------------------------|
| agent.py |
| execution_router.py |
| pre_tools*.py |
| session / fact / skill helpers |
+--------------------+----------------------+
|
v
+-------------------------------------------+
| AXIS 2 : EXECUTION |
|-------------------------------------------|
| tools.py |
| garliclang_bridge.py |
| search.py |
| security.py |
+--------------------+----------------------+
|
v
+-------------------------------------------+
| AXIS 3 : SAFETY AND RECOVERY |
|-------------------------------------------|
| gvcs.py |
| gvcs_core.py |
| gvcs_pipeline.py |
| patch_verify.py |
| snapshots.db / pending_patches.py |
+-------------------------------------------+
Meaning:
Axis 1 decides.
Axis 2 acts.
Axis 3 proves, saves, rolls back, and closes safely.
If you lose Axis 1:
the system cannot reason well.
If you lose Axis 2:
the system can talk but cannot do work.
If you lose Axis 3:
the system can work, but cannot be trusted in production.
3. REQUEST FLOW, STEP BY STEP
The practical request flow is:
+------------------+
| user enters text |
+---------+--------+
|
v
+---------------------------+
| web route receives input |
+-------------+-------------+
|
v
+---------------------------+
| agent.py run_agent |
+-------------+-------------+
|
+--> check special path first?
| |
| +--> gl: prefix ?
| | -> direct GarlicLang run
| |
| +--> anchor command ?
| -> direct anchor handling
|
v
+---------------------------+
| chat mode or work mode ? |
+-------------+-------------+
|
+------+------+
| |
v v
+----------------+ +--------------------------------------+
| chat mode | | work mode |
| text first | | tool capable |
+----------------+ +--------------------------------------+
|
+--> GL inline pattern ?
| -> garliclang_bridge
|
+--> skill match ?
| -> GL-DIRECT
|
+--> compound natural language ?
| -> pre_tools plan
|
+--> explicit [tool:...] ?
-> execution_router.parse_tools
|
v
+------------------+
| security checks |
+--------+---------+
|
v
+------------------+
| tools.py action |
+--------+---------+
|
v
+------------------+
| result to agent |
+--------+---------+
|
v
+------------------+
| answer to user |
+------------------+
This is why garlic-agent is layered.
It is not "LLM says and shell runs".
There are multiple gates before effects happen.
4. MODE SYSTEM
There are really several execution paths, not one.
+--------------------------------------------------------------------------------+
| MODE / PATH TABLE |
+----------------------+---------------------------------------------------------+
| path | meaning |
+----------------------+---------------------------------------------------------+
| normal chat | answer text, maybe with RAG/provider logic |
| work mode | tool capable path |
| gl: prefix | strongest direct GarlicLang route |
| GL inline | lines like run/print/read patterns go direct to GL |
| GL-DIRECT skill | keyword hit triggers direct skill to GL |
| pre_tools compound | natural language multi step planning path |
| explicit tool syntax | [tool:...] parsed by execution_router |
| anchor command | direct anchor handling |
+----------------------+---------------------------------------------------------+
So there are not just "chat vs work" modes.
There are multiple fast lanes and bypass lanes inside work mode.
5. WHY GARLICLANG EXISTS
GarlicLang is a second execution language inside the system.
It exists because natural language alone is too loose for repeated,
verifiable, checkpointed operations.
ASCII picture:
natural language
|
v
vague intention
|
v
LLM response quality varies
Versus:
GarlicLang source
|
v
parser
|
v
interpreter
|
v
explicit steps:
- write file
- read file
- run
- verify
- repeat
- checkpoint
- restore
- report
So GarlicLang is the "structured action lane".
It is especially good for:
- repetitive execution
- verification loops
- checkpoint / restore style control
- Korean friendly scripted automation
- crosscheck style workflows
This is why the architecture has both:
LLM free-form reasoning
and
GarlicLang structured action
6. TOOL LAYER, VISUALLY
+--------------------------------------------------------------------------------+
| tools.py : THE EXECUTION HUB |
+------------------+-------------------------------------------------------------+
| tool | role |
+------------------+-------------------------------------------------------------+
| read | read files |
| exec | run commands |
| write | write files |
| patch | patch file text |
| search | search knowledge |
| snapshot_list | list snapshots |
| restore | restore snapshot |
| app | app control |
| screen | screen control |
| gvcs | read only version state wrapper |
| inspect | read only investigation command |
+------------------+-------------------------------------------------------------+
This means garlic-agent is not only a code patcher.
It can operate across:
- files
- shell
- db-backed search
- snapshot restore
- app and screen surface
- version state inspection
So the tool layer is the "hands" of the system.
But the hands are not free.
They sit behind security.py and closeout rules.
7. SECURITY SHAPE
security.py is not a full OS sandbox.
It is the internal gatekeeper.
Measured policy examples in your paste include:
blocked commands:
rm -rf /
rm -rf ~
mkfs
dd if=
sqlite3
DROP TABLE
DELETE FROM
ALTER TABLE
TRUNCATE
allowed dirs:
~/garlic-agent/
So the logic is:
agent wants action
|
v
security.py asks:
- is path allowed?
- is command blocked?
- does this inspect command violate rules?
|
+--> NO -> block
|
+--> YES -> pass to tools.py
That makes security.py the boundary between "reasoning"
and "actual effect".
8. GVCS IS THE SURGICAL SAFETY KERNEL
This is the most important non-obvious part.
Most AI agents stop at:
"I wrote a patch"
garlic-agent continues to:
"I validated, saved, diffed, tested, and can roll back"
ASCII kernel map:
+--------------------------------------------------------------------------------+
| GVCS |
+--------------------------------------------------------------------------------+
| gvcs.py : command router |
| gvcs_core.py : minimal orchestrator |
| gvcs_pipeline.py : dry-run and post-apply pipeline |
| gvcs_avl.py : ErrorBoundary observer layer |
| gvcs_types.py : PatchContract / HealthReport / StructuredError / Verdict |
| gvcs_contract.py : parse patch contract |
| gvcs_gate.py : PASS_GATE helper |
| gvcs_recovery.py : backup and rollback kernel |
| gvcs_persist.py : move logs and patch artifacts |
| gvcs_meta.py : sessions, tags, verify, briefing |
| gvcs_impact.py : AST impact analysis |
| gvcs_trace.py : trace baseline / compare / report |
| gvcs_cmd_* : split command modules |
+--------------------------------------------------------------------------------+
The clean mental picture:
patch proposal
|
v
PatchContract
|
v
dry-run pipeline
|
v
ErrorBoundary observation
|
v
HealthReport
|
v
decision
|
+--> reject
|
+--> allow real patch
|
v
post-apply validation
|
v
save / diff / regression / pytest / closeout
So GVCS is not "git clone".
It is a patch surgery workflow built for this system.
9. GVCS PATCH FLOW, FULL ASCII
This is the heart of safe modification.
+----------------------+
| patch_xxx.py exists |
+----------+-----------+
|
v
+----------------------+
| cmd_patch |
| in gvcs_core.py |
+----------+-----------+
|
v
+----------------------+
| PatchContract parse |
+----------+-----------+
|
v
+--------------------------------------+
| run_dryrun_pipeline(contract, pr) |
+----------------+---------------------+
|
v
+--------------------------------------+
| ErrorBoundary.run |
+----------------+---------------------+
|
v
+--------------------------------------+
| _run_dryrun_bundle_wrapper |
+----------------+---------------------+
|
v
+--------------------------------------+
| _run_dryrun_bundle |
+----------------+---------------------+
|
v
+--------------------------------------+
| HealthReport returned |
+----------------+---------------------+
|
v
+--------------------------------------+
| decision / PASS_GATE judgment |
+-----------+--------------------------+
|
+-------------+-------------+
| |
v v
+----------------------+ +------------------------------+
| reject / warn / stop | | real patch allowed |
+----------------------+ +---------------+--------------+
|
v
+------------------------------+
| run_post_apply_pipeline |
+---------------+--------------+
|
v
+------------------------------+
| ErrorBoundary.run |
+---------------+--------------+
|
v
+------------------------------+
| _run_post_apply_wrapper |
+---------------+--------------+
|
v
+------------------------------+
| _post_apply_validation |
+---------------+--------------+
|
v
+------------------------------+
| HealthReport returned |
+---------------+--------------+
|
v
+------------------------------+
| save / diff / test / close |
+------------------------------+
This is why your system is different from naive "AI patch engines".
It does not trust the patch itself.
It trusts the measured pipeline around the patch.
10. WHY THE MEASURE LAYER MATTERS
There is a fourth hidden axis beyond brain/execution/safety:
the measure layer.
Measured in your paste:
measure_scripts files : 71
measure_scripts lines : 12901
This means the project has an explicit diagnostic culture.
ASCII role:
bug suspicion
|
v
measure / reproduce / diag
|
v
visible failing case
|
v
patch design
|
v
re-run measure
|
v
fail to pass transition
So "measure" is not decoration.
It is the bridge between:
"I think this is wrong"
and
"I can prove exactly where it breaks"
That is why the system can sustain many changes without collapsing.
11. DATA LAYER
The storage side is also not trivial.
+--------------------------------------------------------------------------------+
| DATA LAYER |
+-------------------+------------------------------------------------------------+
| file/db | role |
+-------------------+------------------------------------------------------------+
| knowledge.db | knowledge index, hybrid retrieval |
| snapshots.db | file snapshots and recovery history |
| chat_sessions.db | chat session state |
| anchors.json | named anchor restoration points |
| fact_ledger.json | fact/execution record |
| config.json | system config |
| secrets.json | sensitive data |
+-------------------+------------------------------------------------------------+
The important point:
knowledge.db = memory for retrieval
snapshots.db = memory for recovery
anchors.json = memory for fast restoration
config.json = behavior settings
So the architecture has both:
semantic memory
and
operational memory
12. BACKGROUND DAEMONS
These background processes make the system feel alive.
+--------------------------------------------------------------------------------+
| BACKGROUND |
+------------------+-------------------------------------------------------------+
| process | role |
+------------------+-------------------------------------------------------------+
| web.py | serves localhost:8080 |
| llama-server | embedding server on :8081 |
| watcher.sh | detect file changes -> auto_index -> knowledge.db update |
| watchdog.sh | keep web.py and llama-server alive |
| autosnap.sh | detect file changes -> gsave -> snapshots.db save |
| integrity_check | startup integrity check |
+------------------+-------------------------------------------------------------+
Visual runtime loop:
file changes
|
+--> watcher.sh -> auto_index.py -> knowledge.db refresh
|
+--> autosnap.sh -> gsave.sh -> snapshots.db refresh
service dies
|
v
watchdog.sh
|
v
auto restart
So the system does not only respond on demand.
It also self-maintains in the background.
13. RUNTIME CALL GEOGRAPHY
Your current measured risk summary already tells a structural story.
High call surfaces:
tools.py : sub=10 shell=1 url=4 total=15
gvcs_pipeline.py : sub=12 total=12
gvcs_meta.py : sub=4 sql=1 total=5
search.py : url=4 total=5
Meaning:
tools.py is where action fanout happens
gvcs_pipeline.py is where patch pipeline fanout happens
search.py is where retrieval fanout happens
So three operational hotspots are:
1) tools.py -> real world effect hotspot
2) gvcs_pipeline.py-> safety pipeline hotspot
3) agent.py -> orchestration hotspot
That exactly matches your risk table.
14. RISK MAP, VISUALLY
+--------------------------------------------------------------------------------+
| RISK PYRAMID |
+--------------------------------------------------------------------------------+
+----------------------+
| tools.py |
| score 41 |
| highest action risk |
+----------+-----------+
|
+----------v-----------+
| gvcs_pipeline.py |
| score 36 |
| pipeline risk |
+----------+-----------+
|
+----------v-----------+
| agent.py |
| score 30 |
| orchestration risk |
+----------+-----------+
|
+----------v-----------+
| gvcs_core.py |
| score 19 |
+----------+-----------+
|
+----------v-----------+
| interpreter.py |
| score 17 |
+----------+-----------+
|
+----------v-----------+
| gvcs_meta.py |
| web_server.py |
| DB surfaces |
+----------------------+
Interpretation:
If tools.py breaks:
execution breaks.
If gvcs_pipeline.py breaks:
patch safety breaks.
If agent.py breaks:
routing and orchestration break.
So these are not just "big files".
They are central pressure points.
15. FILE WORLD VS CONTROL WORLD
A very useful clean split is this:
+--------------------------------------------------------------------------------+
| FILE WORLD |
+--------------------------------------------------------------------------------+
| source .py files |
| docs/.md |
| skills/ |
| tests/* |
| logs/* |
| backups |
+--------------------------------------------------------------------------------+
+--------------------------------------------------------------------------------+
| CONTROL WORLD |
+--------------------------------------------------------------------------------+
| agent.py : decides what path to take |
| execution_router.py : decides what tool call means |
| security.py : decides if action is allowed |
| tools.py : performs action |
| gvcs_core.py : decides if patch flow can continue |
| gvcs_pipeline.py : validates lifecycle |
| gvcs_gate.py : decides auto gate judgment |
| gvcs_recovery.py : restores if needed |
+--------------------------------------------------------------------------------+
This split matters because:
files are the body
control modules are the nervous system
16. THE DOCUMENT STACK
The markdown stack also has roles.
Best current practical order from your paste:
archall
= the current measured world map
patchrules
= the current safe operating manual for patches
SOUL.md
= behavioral constitution for the agent
TOOLS.md
= tool contract explanations
CHANGELOG.md
= history of what actually changed
HANDOVER.md / ONBOARDING.md
= helper onboarding docs, but can drift and become stale
ASCII hierarchy:
current state truth -> archall
patch law -> patchrules
agent constitution -> SOUL
tool explanations -> TOOLS
historical memory -> CHANGELOG
human onboarding summaries -> HANDOVER / ONBOARDING
This is why older onboarding text can be wrong while archall is still right:
archall is regenerated from measured state.
17. WHY archall AND patchrules BOTH EXIST
You asked this before. In the full system map, the reason is obvious.
+--------------------------------------------------------------------------------+
| WITHOUT archall |
+--------------------------------------------------------------------------------+
| you know how to patch, |
| but not what the current system actually looks like |
+--------------------------------------------------------------------------------+
+--------------------------------------------------------------------------------+
| WITHOUT patchrules |
+--------------------------------------------------------------------------------+
| you know what the current system looks like, |
| but not how to patch it safely |
+--------------------------------------------------------------------------------+
So:
archall = map
patchrules = surgery protocol
A map is not a surgery protocol.
A surgery protocol is not a map.
Both are needed in a system this dense.
18. A VERY PRACTICAL "HOW TO THINK ABOUT IT" MODEL
If you want one mental compression that still stays accurate, use this:
+--------------------------------------------------------------------------------+
| GARLIC-AGENT = 8 CONNECTED MACHINES |
+--------------------------------------------------------------------------------+
| M1 | web machine | receives requests |
| M2 | agent machine | decides route and reasoning |
| M3 | provider machine | generates candidate response |
| M4 | security machine | blocks unsafe actions |
| M5 | tool machine | performs file/shell/search/app/screen actions |
| M6 | GL machine | runs structured Korean friendly scripts |
| M7 | gvcs machine | validates, snapshots, diffs, rolls back |
| M8 | measure machine | reproduces, diagnoses, and proves behavior |
+--------------------------------------------------------------------------------+
And the total loop is:
user asks
-> system routes
-> provider reasons
-> security filters
-> tools act
-> gvcs proves
-> measure explains
-> user sees a controlled result
That is the whole system in one sentence.
19. IF THIS SYSTEM WERE DRAWN AS A CITY
This is another accurate ASCII picture.
+--------------------------------+
| CITY GATE |
| web_server / routes / auth |
+---------------+----------------+
|
v
+--------------------------------+
| CENTRAL GOVERNMENT |
| agent.py / execution_router |
+-------+----------------+--------+
| |
| |
v v
+--------------------+ +----------------------+
| POLICE / GATE | | FOREIGN EMBASSIES |
| security.py | | providers |
+----------+---------+ +-----------+----------+
| |
+-----------+-------------+
|
v
+-----------------------------+
| INDUSTRIAL DISTRICT |
| tools.py |
+----+-----------+------------+
| | |
v v v
+-----------+ +----------+ +-----------+
| filesys | | db zone | | GL zone |
+-----------+ +----------+ +-----------+
\ | /
\ | /
\ | /
v v v
+--------------------------------------+
| AUDIT / COURT / ARCHIVE |
| gvcs + patch_verify + logs |
+----------------+---------------------+
|
v
+--------------------------------------+
| OBSERVATORY / LABORATORY |
| measure scripts / diagnostics |
+--------------------------------------+
This city metaphor is still faithful to the real file roles.
20. THE CLEANEST PHONE-BASED STORY
Why this architecture makes sense on a phone:
- web ui gives a stable entry point
- Termux gives local file and shell power
- local db gives persistent searchable memory
- background scripts keep services alive
- gvcs compensates for fragile AI patching
- GarlicLang compensates for vague natural language
- measure scripts compensate for guesswork
So on desktop this might look like:
IDE + git + task runner + test harness + db + scripts + agent shell
On your phone it becomes:
one self-contained operational stack
That is why the architecture is unusual.
It compresses multiple desktop era roles into a phone-driven workflow.
21. FINAL MASTER DIAGRAM
+================================================================================+
| GARLIC-AGENT |
+================================================================================+
| |
| USER SURFACE |
| ---------- |
| phone browser -> localhost:8080 -> web_server.py -> route modules |
| |
| CONTROL PLANE |
| ------------- |
| agent.py |
| -> mode routing |
| -> rule loading |
| -> history + RAG |
| -> provider call |
| -> tool parse |
| -> response assembly |
| |
| EXECUTION PLANE |
| --------------- |
| security.py -> tools.py -> file/shell/db/app/screen/GL |
| |
| STRUCTURED ACTION PLANE |
| ----------------------- |
| GarlicLang parser/interpreter -> repeat / verify / checkpoint / restore |
| |
| SAFETY PLANE |
| ------------ |
| gvcs.py -> gvcs_core.py -> gvcs_pipeline.py -> HealthReport -> decision |
| -> post-apply validation -> save/diff/test/rollback |
| |
| MEMORY PLANE |
| ------------ |
| knowledge.db / snapshots.db / chat_sessions.db / anchors.json / config.json |
| |
| BACKGROUND PLANE |
| ---------------- |
| watcher.sh / watchdog.sh / autosnap.sh / llama-server |
| |
| MEASURE PLANE |
| ------------- |
| measure scripts -> reproduce -> diagnose -> verify behavior |
| |
+================================================================================+
SIMPLE TRUTH:
it thinks, acts, verifies, remembers,
restores, and measures.
22. FINAL VERDICT
[FACT] The best exact ASCII summary is:
garlic-agent is a layered AI operating environment where
web routes receive,
agent orchestrates,
providers generate,
security filters,
tools execute,
GarlicLang structures,
GVCS verifies and restores,
databases remember,
background daemons maintain,
measure scripts prove.
[FACT] If someone understands the 5 files below,
they understand the skeleton of the whole project:
- agent.py
- tools.py
- gvcs_pipeline.py
- gvcs_core.py
- garliclang/garliclang/interpreter.py
[FACT] If someone understands the 3 axes below,
they understand the whole design logic:
brain
execution
safety
[FACT] If someone understands the 1 hidden truth below,
they understand why this system survives complexity:
measurement is treated as part of the architecture,
not as an afterthought.
Top comments (0)