DEV Community: Sergey Tolkachyov

ProcessForge 1.2.0 Released: Performance Optimizations and Improved Reliability

Sergey Tolkachyov — Mon, 19 Oct 2026 08:47:32 +0000

ProcessForge 1.2.0, a new version of the open-source framework for organizing and running processes involving AI agents, was released on 18 October 2026. This release focuses primarily on optimizing PF's internal mechanisms, improving the reliability of long-running processes, and resolving issues encountered in practical work with multiple AI agents.

Optimizing Work with Large Volumes of Data

In Forge / Factory multi-agent mode, ProcessForge can launch separate, independent AI agent sessions (workers). Each worker receives its own assignment (Assignment), a context capsule (Capsule) containing the necessary knowledge and instructions, and a limited area of responsibility (Scope).

This allows several agents to work on different parts of a project in parallel without interfering with one another.

During extended work with workers launched through the command shell (shell workers), large volumes of logs, events, and task execution history began to accumulate. A problem emerged: some PF operations repeatedly read and parsed data that was not directly relevant to the current work. As the history grew, this created unnecessary overhead.

Version 1.2.0 reworks several mechanisms.

1. Moving Event Journals to SQLite

Previously, NDJSON journals were used to store project and hook events. When the history grew large, some operations required records to be read repeatedly.

Project events and raw hook events (raw hooks) are now stored in two local SQLite databases with indexes.

This makes it possible to find the required records quickly, check that events are unique, and process new data without repeatedly scanning the entire accumulated history.

PF does not require a separate database server to be installed. Shell worker output logs, telemetry, and session transcripts remain separate files.

2. Faster Selection of the Current Work

In PF, work is defined by a specific Run (a process run), Assignment, and associated context. Previously, even when the required assignment was specified explicitly, the system would sometimes scan the project's entire Run and Assignment history. Now, when the identifiers have been unambiguously verified, PF goes directly to the selected work without iterating over the other assignments.

On a synthetic project with 400 Runs and 800 Assignments, the number of reads required for this selection dropped from 1,202 to 4, while the operation time fell from approximately 3.2 seconds to 5–6 milliseconds.

3. Reusing Parsed YAML

ProcessForge uses YAML to describe processes, assignments, settings, and other structured data. Repeated reads of unchanged documents can now reuse an earlier parse stored in process memory. PF still checks the current file contents. If a document has changed, the system parses it again. Access control and context integrity checks remain enabled.

Improved Recovery After Worker Failures

In multi-agent mode, the Process Execution Inspector monitors tasks carried out by external workers. It tracks the state of launched processes, their activity signals (heartbeat), completion, and results. Once an assignment has been carried out, the Inspector gathers the required artifacts through the collect mechanism. During extended work, a worker may finish while result collection fails.

Previously, persistent automatic collection errors could cause an operation known to be failing to be repeated. PF now distinguishes between temporary errors, where a retry makes sense, and persistent failures that require a separate recovery step. Results that have already been collected remain in the history. Assignment execution state and Runtime health are displayed separately. This helps prevent the results of an agent's lengthy work from being lost because of a problem during result processing.

Safely Continuing Work in a New Session

Another feature of long-running AI processes is the need to continue work after an agent's session ends. ProcessForge provides a Continuation mechanism. It allows a specific Work to be resumed while retaining its association with the Run, Assignment, context capsule, and selected process. When work resumes, the system checks its state, permissions, and context freshness again. The new session does not gain the right to replace the assignment, expand the Scope, or choose another task on its own simply because the earlier conversation context is unavailable.

Expanded Capabilities of the ProcessForge MCP Server

Version 1.2.0 significantly expands the set of tools available to AI agents through MCP. Previously, the PF MCP server mainly provided access to project context, knowledge search, Work creation, and process stage management. Many operations, especially those involving the launch of other AI agents, required PF command-line tools. Additional Core capabilities are now available directly through MCP.

Managing Workers

In Forge / Factory multi-agent mode, the orchestrator distributes work among separate, independent AI agent sessions. Each worker receives a limited assignment (Assignment), a prepared input context, and its own area of responsibility (Scope).

Four tools have been added for managing workers through MCP:

pf.worker.prepare — prepare the worker's input data, context, and constraints.
pf.worker.start — launch the worker through the selected registered Runtime Driver. The launch is asynchronous: control returns to the orchestrator immediately.
pf.worker.status — check execution status, with support for state reconciliation and collection of completed results.
pf.worker.collect — collect the worker's results and verify the report, checksums, and execution attempt details.

During preparation and launch, you can also specify the model (model) and reasoning effort (reasoning_effort).

The orchestrator can therefore manage the worker lifecycle through MCP without manually invoking CLI commands.

PF's constraints still apply: a worker can only be launched through a registered agent driver, with a specific Assignment and a pinned context.

Continuing Work Across Sessions

The tools pf.continuation.status, pf.continuation.create, and pf.continuation.resume have been added. They allow previously started work to be found, a continuation point to be created, and work to be resumed in another AI agent session. The specific Run, Assignment, pinned process, and immutable context are preserved. The new session does not gain the right to choose a different assignment arbitrarily or expand its area of responsibility.

Searching for Knowledge Within a Work

The new pf.work.search and pf.work.resolve tools allow agents to search for and retrieve resources permitted for a specific assignment. Unlike the general pf.search, which works with project context resources, these tools also take into account the permissions pinned to the Work and the constraints of the current process stage.

Discovering Available Commands

The tools pf.actions.list and pf.actions.describe have been added. They allow an agent to find out which CLI commands and MCP tools are supported by the installed version of ProcessForge, which parameters they accept, and which parameters are required.

pf.actions.list describes the actions available in the installed PF version, their names, and their purpose. The catalog can be filtered.
pf.actions.describe describes the exact parameters of the selected action: required fields, types, permitted values, constraints, and declared side effects.

The tools pf.runtime_driver.list and pf.runtime_driver.describe have been added for working with drivers. They show which drivers are registered and available in PF without exposing their internal launch commands or environment variables. These tools help the orchestrating AI agent choose how to execute a Work. A driver defines how PF passes prepared work to a worker, removing the need to guess launch methods, paths, commands, or arguments. When this information was unavailable, an agent would often inspect the executable's source code to find those details. The workflow is now more convenient.

Session Management and Message Recording

The tool pf.session.heartbeat has been added to renew an existing session's registration in the Agent Ledger (the PF workplace's "gatekeeper's log"), along with pf.chat.record for recording an agent's message in its own session log. The new pf.work.cancel tool allows an agent's assignment to be cancelled. All tools that change state retain authorization checks. The relevant operations require an explicit apply: true.

Why Were These Changes Made?

The goal is to give AI agents a unified programmatic interface for working with ProcessForge. The orchestrator can now use MCP to obtain context, manage Work, launch workers, monitor their state, collect results, and continue work across sessions.

The workers themselves do not have to connect to the PF MCP server: they can work independently with a context that has already been computed and prepared, and return results through the defined contract. This reduces dependence on command-line tools and a particular runtime environment while preserving PF's control over processes, permissions, and results.

Clearer Instructions for Agents Entering a Project

The root AGENTS.md is now the main entry point into a project. It contains the mandatory contract for an agent's work with ProcessForge: how to obtain context, select or continue a Work, stay within its area of responsibility (Scope), and move through process stages. A problem arises during extended work: AI agents tend to append new rules, conclusions, and instructions to AGENTS.md. The file gradually grows, while different AI clients have their own limits on the amount of instructions they load. As a result, some rules may fall beyond the available limit and never reach the model's context.

PF 1.2.0 adds a mechanism for checking the size of startup instructions (Instruction Accounting).

The mandatory PF contract is limited to 4,096 bytes. The system can also check the size of the entire file and the chain of included instructions against explicitly configured limits for a particular AI client. If it detects a risk that mandatory instructions will be truncated, PF blocks the relevant change. If warning mode is configured, it reports that the limit has been exceeded.

PF does not automatically shorten or rewrite the user's instructions.

Separate diagnostic profiles are available for different AI clients. They help assess which files should be loaded and whether they fit within the known limits. Whether the instructions actually reach the model requires a separate check. The mechanism is intended to prevent accumulated instructions from causing an agent to miss the mandatory rules for working with the project. These checks run when the entry point is prepared, changed, or diagnosed; they do not continuously monitor the file in the background. The 4,096-byte limit applies to the PF-managed contract, rather than the whole of AGENTS.md.

Prepared workers can also begin work with instructions and a capsule that have already been supplied, without connecting to their own PF MCP server or creating the Work again. This reduces unnecessary context and preserves the division of responsibility between the orchestrator and workers.

Managing Temporary Files

Project temporary files should now be placed in .pf/tmp/, with separate directories allocated to workers. The optional PF app-server now supports configurable notifications about temporary files that have not been modified for a long time. PF does not delete them automatically: workers may still be using them.

What Does This Mean in Practice?

ProcessForge continues to evolve as a framework independent of any particular AI model or runtime environment. In the simple Garage mode (the 1-1-1-1 mode: one person, one project, one agent, one run), a single agent can work with a project without starting the PF app-server. The entire project history, including the history of decisions, is stored in the project's .pf directory.

In Forge / Factory mode, multiple workers can operate in parallel with separate contexts and assignments, controlled access to resources, result verification, and work handoffs between sessions. All of the "project bookkeeping" remains in the project's .pf directory, but a shared process, pf-app-server, is required to organize the workflow correctly. It is optional in Garage mode.

The changes in version 1.2.0 are primarily intended to keep this system responsive and manageable as the project, task count, and accumulated history grow.

Upgrade process: when upgrading from an earlier version, preserve the state of your projects and perform a separate migration of the old event journals (tell the agent to use the suggested migration tool).

ProcessForge — processes, knowledge, tools, and execution control for AI agents.

Process Forge: a framework for creating AI processes

Sergey Tolkachyov — Fri, 07 Aug 2026 05:55:40 +0000

During the 2026 New Year holidays, in one of the Joomla community chats, a fellow colleague shared a prompt for an AI agent and the result of that prompt. A week before that, he had tried Gemini CLI for the first time. Until then, I had only used AI in web versions, and overall that suited me fine. When I saw that wall of text, the CLI request, and the wall of response, the first thing that hit me was:

I DO NOT WANT to learn all this stuff! Something new again, I'm tired of it...

Then came the stages of trial and error, attempts to use ready-made community skills packages from GitHub with role-based suggestion like

"you are a super-duper mega-backend Joomla developer with 40 years of experience, make it beautiful for me"

Somewhere in the middle of this half-year I started formalising my processes. And by processes I do not mean only development, but also SEO, analytics, business analysis, process study and process design, and so on. In the end, as a rule, all of that is either connected with or leads to a Joomla site. Formalisation brought me to an understanding of several basics that are common to all processes. More on that below.

Now I want to present to the honourable public my work on a framework for creating formalised work processes for AI agents: Process Forge (GitHub).

I ask experienced vibe coders to forgive me in advance for any obvious points or long-known theses if they appear here. Workload did not allow me to spend too much time searching and watching what others were doing. I had to switch myself onto new tracks.

Starting Points

To answer the questions "what is all this for?" and "why this way?", I will give several starting points that I mostly felt out through practice over these six months and from which I proceeded when creating Process Forge. Some of these conclusions later found confirmation in other people's findings that I noticed in articles or social media posts:

An AI model's internal knowledge about a technology stack is most often seriously behind real modern practice. This varies a lot from stack to stack. You can add "for now", but in general this is still a relevant premise.
For an AI agent to work properly, it needs to be given everything a human is given for work: knowledge and tools, ready-made templates for reuse.
An AI agent needs a certain amount of freedom, but within a defined corridor, along a specified vector.
You must not be tied to any one AI provider ecosystem. There must be a way to "switch the brains" (there should be no .codex, .claude, and so on as the agent's home base; there should be something neutral, even though the agents themselves try to bind you to their ecosystem).
All project memory and processes must be structured in files.
You yourself must first understand WHAT is happening, HOW, and WHY. Without that, AI will only bring more chaos into your life.

When we work with AI agents, and with AI in general, we expect the work to be done quickly and well, because this is Artificial, damn it, Intelligence. But it turned out not to be so. Instead of a shovel, you were given a turbo-excavator that says to you: "I am ploughing the field, my wheel fell off, I will quickly fix it with a temporary fallback and put a track on one side." You still have to learn how to work with this thing, and know where and how to apply it properly. I should say right away that almost everything written here is the result of my own heuristics and is therefore purely subjective. Only several months later did I get acquainted with AI Factory (link one, link two (Habr)) and GSD Core, but it was already too late, because I was already working full steam with my own tool. There may well be other similar tools.

Process Forge Concepts

I will lay out the concepts in the order in which they appeared and were tested in "combat" conditions as they evolved. This way the history and logic of the decisions will be clearer.

Process Instead of Chat

After two months of working in chat mode and with ready-made community skills packages from GitHub, with role-based suggestion like "you are a super-duper mega-backend Joomla developer with 40 years of experience, make it beautiful for me", a quick search and a discussion with AI about my own doubts around all of this led me to the conclusion that I needed to build a development process. At first, only for development.

Chat history cannot be a reliable source of project data or project memory. Every new session starts from zero for the agent: tabula rasa. The agent has to be loaded with project context: what this thing is and how to deal with it. That is why all project memory and processes must be structured and stored in files. In spring I came across the word "artifact" in the sense of "a file produced as the result of an autonomous process". As far as I can judge by what is happening in the industry, everyone is accumulating their own Markdown files: in folders, in Obsidian, or somewhere else, with different instructions, skills, and so on inside.

My request was immediately for a process, so after several days of discussion I arrived at an artifact-based development flow. It was a set of folders and files describing the rules for working with projects. They described the workflow stages that I used and improved over three months while creating Joomla libraries, plugins, and components. You can get a general sense of the stages under the cut. In a modified form, this entered Process Forge as one of the "out-of-the-box" processes.

Example process stages:

Stage	Meaning	Requires	Fills
`artifact-policy`	Normalises artifacts before the stages	`task-record`, `project-context`	`artifact-index`, `missing-artifacts-created`
`flow-orchestrator`	Chooses the current/next stage	`task-record`, `artifact-index`, `project-context`	`stage-decision`, `next-skill-handoff`
`intake-scope`	Records the task, boundaries, and success criteria	`task-request`, `project-context`	`brief`, `scope`, `task-record`
`investigation`	Gathers facts, causes, and the impact surface	`brief`, `scope`, `project-context`	`investigation-report`, `impact-analysis`
`domain-surface`	Describes domains, ownership, and risks	`scope`, `investigation-report`, `impact-analysis`	`decision-log`, updated `impact-analysis`
`architecture-plan`	Designs the solution and the order of changes	`brief`, `scope`, `decision-log`, `impact-analysis`	`architecture`, `implementation-plan`
`implementation`	Makes changes according to the plan	`architecture`, `implementation-plan`, `decision-log`	`changed-files`, `change-summary`
`code-assurance`	Checks, review, test cases, browser proof	`changed-files`, `change-summary`, `implementation-plan`	`review-findings`, `test-plan`, `test-cases`, `browser-verification-report`
`release-delivery`	Release packaging/delivery	`change-summary`, `review-findings`, `test-cases`	`release-notes`, `migration-notes`, `patch`
`evolve`	Extracts reusable lessons into rules/extensions	`patch`, `evolution-cursor`, `logs`	`evolution-report`, `updated-rules-or-extensions`, `updated-cursor`

This is one of the earlier versions of the artifact-based development flow.

In addition, the whole flow maintained task-log, agent-log, verification-log, and tool-telemetry.ndjson; the specific log depended on the stage. Telemetry records tool usage and the reasons for using those tools. For example, if MCP PhpStorm could not perform the required action or got stuck for some reason, plain shell was used as a fallback.

Connecting Knowledge to an AI Process

The knowledge built into AI models themselves usually lags behind current reality. Top paid models have some idea of recent events, but even then not always. In my subjective assessment, web search also costs AI agents more time and tokens, so all current knowledge should be close at hand, and the agent should build its context from it. Almost anything can be used as reference material:

source code of current versions,
snapshots (local copies) of official documentation,
your own or other people's development articles,
your notes with recipes for solving a particular task,
links to sites.

I work with Joomla, so in my stash I have:

source code of several Joomla core branches,
source code of the main Joomla extensions I work with regularly (JoomShopping, RadicalMart, and so on),
copies of official documentation for web full stack: manual.joomla.org, HTML / CSS / JS / PHP, and documentation for several frameworks,
my own articles and some articles by fellow colleagues,
documentation for various APIs, which I supplement with dumps of real responses if it is REST,

and so on. Yes, I know that Context7 exists (the service and MCP for machine documentation), but as far as I remember it started limiting requests at some point and, predictably, introduced pricing plans with request packages.

Overall, this section of the article lives in the plane of on-premise vs SaaS: either we do it ourselves for ourselves, by hand; or someone else does it for us, but for money. For now I am, as you have probably already guessed, a supporter of the former )) Naturally, with this approach you, or your AI agent, take on the obligation to keep knowledge up to date.

Connecting Tools, MCP, and Templates

Templates

I will start with templates because they are simple: in my case these are separate ready-made pieces of code that can be copied, slightly adapted, and they are ready. For an AI agent, it is better to put them into folders and give each folder a README.md describing what this template is and how to work with it.

But it does not have to be only code: design fragments, video fragments (footage), and so on. Whatever your agent works with.

Tools and MCP

By tools I mean what the AI agent can use on your device. For a developer this may include git, GitHub CLI, pipeline runs, linters, fixers, packagers/builders, local and remote test stands. For an SEO \ GEO specialist these may be small utilities for automated access to various service APIs (Yandex APIs for Wordstat and SERP data collection), Screaming Frog CLI, and so on. I suppose that a conventional video-production setup also has similar tools of its own.

The most important point is that the tool must be configured globally on the workstation so that different projects can use it in the same way: one builder instance is used across all 80 plugins you write.

MCP in this case appears as the same kind of tool, just available through Model Context Protocol. It may be Playwright / Chrome DevTools / Firefox DevTools for tasks that require a browser. It may be MCP IDE PhpStorm in my case, Serena for symbolic code analysis, and so on.

I noticed that when working with code through MCP IDE, there are fewer problems with file encodings and file-system permissions. Also, through MCP the agent can receive more information from inspections and run tests. But it can also run shell commands through the PhpStorm console, even though it already has direct access to the console, so catch it in time before it starts doing nonsense.

Processes Again

In the context of working with Joomla and its extensions, I try to work through a full engineering process: the required functionality is discussed, we plan the implementation, then write the code, run end-to-end tests, finalise and build the package, and publish a release according to semver. After that, post-release tasks roll in: update or write documentation from scratch in two languages, prepare screenshots in two languages, video in one language, publish announcements about new versions with descriptions on 15+ platforms...

As I came to understand how to work with AI agents, the results of our joint work started accumulating. A new problem appeared: when should all this be checked and published? With agents, less time was spent on code, but more time on planning and testing. And post-release tasks did not disappear...

So the next experiment was to try adapting the agent for writing documentation, preparing screenshots, and publishing all of this to the site. The file-based process that had already been worked out handled this too. With great distrust, over several dozen iterations, I began expanding the agent's area of responsibility and eventually reached full release publication. In general it works, but there is of course less human spirit in it than one would like.

Often, certain thoughts or pieces of information circle around us for a long time, appearing before our eyes several times before we notice and understand them. In this case, an understanding began to form that I was surrounded by processes of different complexity in my work. It became logical to go one level above coding and identify a universal process entity, where there may be different numbers of stages, artifacts between them, relationships, and so on. That is how Process Forge began to appear.

It now has internal processes, out-of-the-box processes, and the ability to create your own processes. Processes can branch, and a parent process can wait for the results of a child process and then continue working.

Platforms and Specialisations

Platforms

The platform entity allows Process Forge knowledge packages to be combined into pluggable packages, and lets you describe the execution environment, templates, and required tools inside them. When you start making "a new plugin for Joomla 6+ that...", the agent understands which platform is meant and adds not only Joomla knowledge to the project context, but also PHP, HTML, CSS, JS knowledge, the required checks package, code style rules, and the Phing extension packager.

Platforms can inherit from one another. For example, you are writing a plugin for the JoomShopping online store, which does not exist separately from Joomla. But JoomShopping has its own separate knowledge sets, which are not needed when working on the clean engine core or another store. And, predictably, when working with JoomShopping we also need knowledge about Joomla.

Specialisations

If our agent writes Joomla code, it needs knowledge for writing code. But if it publishes an article or works with modules on the site in the admin panel, it does not need PHP, JS, or Joomla extension architecture knowledge. It needs knowledge of the admin panel, of the REST API for faster work, maybe basic HTML and the CSS framework of your project's site, image-processing rules, media-content placement rules (what to put in which folder), and so on. That is why specialisations appeared: they combine the knowledge needed for a particular specialisation.

The point of this entity is that the backend may work with Joomla, or with Laravel, or with Django and Python. Platforms provide applied knowledge about the language, architecture, and tools. Specialisations provide general abstract context: patterns, approaches, principles. Specialisations may also connect their own knowledge, tools, templates, MCP, and so on.

Cascading Project Context Computation

In Process Forge, context is not stored in one large prompt or skill. It is computed as a cascade from several levels, by analogy with merging arrays/objects: each next level inherits the data from the previous ones and refines it for a specific situation.

General workspace rules are supplemented by company, area, platform, and project knowledge, then by process, task, and concrete agent settings. More local levels can extend or override general parameters. As a result, the agent receives not the entire accumulated mass of information, but the relevant context assembled immediately before the task is performed.

In general terms, the context-computation logic is as follows:

Workspace
Company / organisation
Area (SEO, development, content...)
Platform (Joomla, WordPress, Symfony...)
Specialisation (backend, frontend, full stack, content, SEO...)
Project
Process (software development / SEO audit / ...)
Task and current stage
Agent role and profile (in multi-agent mode)

Each next context source is layered over the already assembled one. The result of this work is a project context snapshot (YAML for machines, Markdown for people), which states:

platform_contracts / platform_stack: selected and available platform contracts
resolved_parameters: final parameters after inheritance and overrides
parameter_resolution: parameter sources, provenance, and conflicts
resolved_context: the result of specialisations, resources, tools, MCP, templates
resolved: final knowledge packages / resources / templates / tools / processes
capabilities: required/optional capabilities and their status
conflicts: specialisation and parameter conflicts
snapshot.health.status: final state: pass, warn, or blocked
freshness / context_policy: freshness policy and state

and some other information.

For a specific task, and in multi-agent mode, even more specific snapshot-capsules are assembled and passed to the agent together with its assignment / process / stage / task layers as machine-readable files.

The General Feedback Mechanism: Evolve

Evolve in Process Forge collects useful conclusions that appeared during work on a task: what should be remembered, improved, checked, or moved into shared experience. It does not change rules and knowledge automatically. First, it formalises such findings as proposals with a clear scope: only for this project, for the workspace, for a package, platform, or the core. Then those proposals can be checked, selected, and only then consciously included in shared materials or updates.

When a proposal turns into an updated knowledge package, template, rule, or other shared material, it is distributed through the normal Process Forge update mechanism. The project sees that an update is available, can prepare it, check it, apply it, and after that rebuild its context with the new version of shared knowledge.

Versioning

Both Process Forge itself and its entities are designed with versioning in mind. Since everything lives as files, as separate packages, you can gradually improve and expand them. Accordingly, you can have your own update server for all parts of your workplace: the Process Forge core, separately processes and platforms, separately knowledge packages and templates. For example, you made process changes after evolve from several machines: you publish a new process version. You created new instructions for working with code: you publish code_instructions_v.1.1.0, and all your workstations receive a new knowledge package. After that, local workers update project contexts and can work with the new knowledge.

Organising Work in Process Forge

In a surprising way, all of this starts to resemble structures built in human companies and organisations. I assume that the human operator should not have to know slash commands, but should simply direct agents in natural language. That is why Process Forge 2 has documentation both for people and for agents.

To get started, you need to set up your machine:

Install the ProcessForge distribution (unpack the archive into your agent area).
Run step-by-step workplace setup with a human involved (there is an auto mode, but at your own risk).
Configure path constants and root directories.
Specify roots for knowledge and local documentation.
Register tools and MCP servers.
Create or import knowledge packages.
Create a registry of reusable templates.
Create platforms from existing resources.
Create specialisations.
Connect project(s) to the workplace.
Create your own processes if the out-of-the-box ones are not enough.
Start working.

Yes, this takes time to set up the machine. But it scales, and in general it has shown itself fairly well.

Process Forge assumes two main operating modes: garage mode and forge mode.

Garage Mode (1-1-1-1)

This is the mode where there is:

one human operator,
one main agent session (console window),
one project,
one active process/run.

The main agent performs the work, runs checks, maintains artifacts, and either finishes the work or hands it off to the next stage or process.

We open a console / chat with the agent, say "immerse yourself in the project through .pf. Tell me what has been done and where we stopped?", and continue working within one project. Physically, you may have two or three independent projects open at the same time, each working in garage mode. And in this garage you have an assistant that uses your tools, uses your knowledge, uses your platforms, and works according to your templates.

Forge / Factory Mode

This is a multi-agent mode where work is divided into independent streams.

Your main agent becomes an orchestrator that receives input data, chooses the process, creates assignments with context capsules, then starts agent sessions (full-fledged agents or subagents), coordinates them, and makes sure agents do not interfere with one another. Then it collects their results and integrates the outcome through result handoffs and reviews.

In this way, work on a project becomes similar to the work of a team or department on a project. They need to be coordinated, and therefore there appears...

Agent Director is a workplace-level role for organised coordination of several agent sessions, processes, or projects. It is not needed in garage mode, but it is needed where there are handoffs, waiting for a suitable executor, errors, parallel work by several orchestrators, or the need to explicitly transfer responsibility. Project agents and orchestrators can send signals to the Director's inbox: for example, that a task is blocked, another executor is needed, an error occurred, or an operator decision is required. Such messages form cases, which the Director takes into account during the next coordination pass.

At the same time, in the current ProcessForge implementation the Director is not a constantly running independent LLM agent. In the PF model it is described as an agent role, but it is executed as a CLI coordination layer: it checks the handoff queue, agent availability, leases, and the state of open cases, but it does not perform tasks itself and does not launch agents. In the future, this role can be developed into a full AI agent that reasons about priorities and complex routes, but for now it is a deterministic mechanism for managing workplace coordination.

The watchman's log. To make it comfortable for agents to work in a Process Forge workplace, there is a "watchman's log" where agents who have "come to work" are recorded. It shows who entered the process, what they saw, what they did, where they stopped, and what risks they left for the next participant.

The log helps quickly restore the course of work without searching through all files and messages. This is important because work can move between agents, tasks, and runs, while the log preserves context continuity. And it is not a separate agent; it is a CLI tool, so we do not spend tokens here.

Given that your computer is turning into a kind of company branch or small office, it may later have not only a Director and a watchman. Over time, it may get a "facilities manager" (some kind of background process) that checks whether anything needs to be done with the workplace: send candidates for improving knowledge packages to a central hub for release, or receive new knowledge packages and intelligently update the contexts of all projects. Or perhaps there may be a "cleaner" (a process that occasionally launches an agent for smart cleanup). But these are already fantasies, somewhat detached from reality ))

Conclusion

In some articles about AI development I have encountered similar ideas: you need to build a pipeline that performs tasks of the same type. The times, apparently, are such in AI that it is easier to create your own custom tool than to take someone else's and adapt to it, or try to customise it. Nevertheless, I will risk sharing my work with the IT community in a field that is completely new to me. I hope it will be useful to someone.

How to work with the component menu in the Joomla admin panel using preset.xml and the plugin.

Sergey Tolkachyov — Sat, 23 May 2026 16:23:17 +0000

The Joomla component has several levels of presence in the admin panel. The simplest level is created by the component installer: if the manifest contains <administration><menu>...</menu></administration>, Joomla will add the item to the protected admin menutype=main. But this is often not enough. A normal component needs groups of links, quick actions, links to categories, fields, workflow, dashboard, separate sets of items for different administrative modules, and the ability to add or hide items dynamically.
To do this, Joomla 6.1 uses the menu preset mechanism.

How to work with preset.xml and modify the admin panel menu using the plugin in this article.

Read the article (in Russian)

CFI Plugin v.2.0.0 Released - Export/Import Joomla Articles to/from CSV

Sergey Tolkachyov — Mon, 19 Jan 2026 09:44:59 +0000

This plugin allows you to export Joomla articles to a CSV file. You can then edit the data in a spreadsheet editor (e.g., Excel or Open Office Calc) and upload the file back. In some cases, this is more convenient and faster. The plugin allows exporting tag IDs, working with custom article fields in Joomla, as well as usually non-editable article properties like hits, modification date, etc.

Initial versions of the CFI plugin were created by developer AlekVolsk for Joomline. He created versions 1.0.0-1.0.16 for Joomla 3. Subsequently, in 2026, the plugin was transferred to WebTolk for further development.

v.2.0.0. What's New?

Refactoring. The plugin has been completely rewritten from scratch.
New Import/Export Interface. Export and import now open in a modal window. Functionality to select article properties, tags, and custom fields for export right before the export itself has been added.
Article Filtering During Export. You can filter the articles you need using standard search parameters in the admin panel, and then export only those: only featured ones, only published ones, only articles from 2 categories, only articles with a specific tag, etc.
Import/Export All Article Data. Previously, the plugin could only export some article data. Now, during export and import, you can change all article data found in the article editing form, even non-editable ones like hits or modification date. This way, you can quickly update all meta-descriptions or just the field data.
Import Custom Fields Only. The articleid field remains mandatory for import. Thus, you can import only custom field data without changing the article data itself.
Joomla 6. The plugin has been rewritten with the current structure for Joomla 4+ and successfully tested on Joomla 6.
For Developers: Pre-processing by Plugins. You can process data with your own plugins of the cfi group on-the-fly, directly before importing or exporting data. Events: onExportPrepareData($event) and onImportPrepareArticleData($event).

System Requirements: Joomla 4.3+, PHP 8.1+.

To update from older versions, release 1.0.16 is available, which adds a new update server.

Extension Page (https://web-tolk.ru/dev/joomla-plugins/cfi-eksport-import-materialov-joomla?utm_source=dev.to)
Extension GitHub (https://github.com/WebTolk/cfi)
Version for Joomla 3 and Joomla 4 (https://joomline.ru/rasshirenija/plugin/cfi.html)
GitHub Repository for Joomla 3+ versions (https://github.com/AlekVolsk/cfi)

Joomla View Logs component v.2.3.0 has been released!

Sergey Tolkachyov — Sun, 11 Jan 2026 11:22:44 +0000

The component allows you to view error logs and notifications in the Joomla admin panel. Logs of both Joomla itself and extensions that use the standard kernel logger are displayed. It works with Joomla 4+, Joomla 5+.

v.2.3.0 What's new?

The option to disable the display of the PHP log has been added in the component settings
Added a message about the inability to delete a PHP log from the log list page
Added a link to download the zip archive in the message about archiving the log
The disabled attribute has been added to the "archive" and "delete" buttons for the PHP log
Fixed the reading path for the PHP log
Fixed links for downloading logs in csv format from the logs list page
Fixed downloading logs in csv format from the logs page (previously logs were downloaded with html code the template)
Fixed translation of column headers of the log table

Extension page
Extension GitHub

Joomla-дайджест. 2-е полугодие 2025 года.

Sergey Tolkachyov — Sat, 03 Jan 2026 17:17:53 +0000

Все главные новости из мира Joomla с июля по декабрь 2025 года в одной статье. Я честно пытался напрячь самые разные ИИ сортировкой постов по смыслу и, к сожалению, ни один из них не справился с этой задачей так, как нужно мне. Поэтому, напрягая собственный интеллект, представляю читателю наш дайджест, который обозревает новости, расширения, шаблоны и статьи из мира Joomla.

Читать на Хабре.

WT IndexNow - send your Joomla urls to search engines via IndexNow protocol

Sergey Tolkachyov — Sat, 03 Jan 2026 09:03:05 +0000

A free package of plugins that provides manual and automatic sending Joomla URLs to search engines for reindexing using the IndexNow protocol (https://indexnow.org).

Supported components

At the moment, the package includes providers for the following components:

Joomla articles and aritcles categories
Joomla contacts and contacts categories
SW JProjects GitHub Joomla Extensions Directory
JoomShopping Joomla Extensions Directory
Phoca Download
Phoca Cart
RadicalMart

The plugin package is designed to send the URLs of Joomla sites to search engines for reindexing using the IndexNow. According to the documentation, the protocol is supported by all major search engines except Google. The protocol is used to receive URLs from sites that need to be reindexed or indexed for the first time as quickly as possible. Sending site addresses in this way will significantly speed up the indexing of new or modified content by search engines. Search engines use this protocol to exchange data with each other, so by sending a URL to one of them, you share it with everyone at once.

Using the IndexNow protocol, no more than 10000 URLs can be sent per day. Keep this in mind when working with content.

WT Yandex map items v.2.0.5 Joomla module has been released

Sergey Tolkachyov — Wed, 30 Jul 2025 05:09:25 +0000

Display data from various component's custom fields like Yandex.Maps placemarks. Joomla articles are displayed as Yandex.maps placemarks. The articles categories and contacts are not displayed yet.

v.2.0.5. What's new?

UX improving

When interacting with a page on mobile devices, if the map is displayed in full width, it starts scrolling instead of the web page. To avoid this situation, an overlay for the map has been added. Now interaction with the map is possible after clicking on the map. The overlay automatically turns on when the cursor leaves the borders of the map container and the map can be scrolled again.

Extension page
GitHub

Joomla 5.2.4 Security & Bugfix Release

Sergey Tolkachyov — Wed, 19 Feb 2025 05:23:10 +0000

Let’s celebrate! The Joomla! Project is pleased to announce the release of Joomla 5.2.4 and Joomla 4.4.11. This is a security and bug fix release for the 5.x and 4.x series of Joomla.

These releases continue Joomla’s high standards in accessible web design, highlighting Joomla's values of inclusiveness, simplicity and security into an even more powerful open-source web platform.

Security Fix

[20250201] - Core - SQL injection vulnerability in Scheduled Tasks component. Read more.

Bug fixes and Improvements with 5.2.4

Fix namespace map creation on PHP 8.4 (#44789)
Fix PHP Warning for debuguser, debuggroup (#44721)
Fix handling of null values on update row (#39607)
Fix cache counting issue - correctly count number of files (#43986)
Fix permissions for manually running scheduled tasks (#36719)
Tag Router: Allow numeric/CSV IDs (Regression) (#44784)
Fix for Composer update to enshrined/svg-sanitize to resolve SVG upload issues (#44746)
Fix for Article cannot be saved successfully on the front-end (#44680)
Fix media downloads with spaces (Follow-up of #37396) (#44745)
Finder Router: Filter out unnecessary query elements (#44055)
Jooa11y plugin and page cache conflicts (#41956)
Fix a11y issue in accordion (role attribute) (#40578)
Remove alt-text for menu items when both image and title are set (a11y fix) (#40675)
Fix breadcrumbs color in light and dark mode (#44212)
Email alt text fix in contact component (#44491)
Web Asset Manager: Incorrect loading of external resource with / at the end (#44774)
Fix media downloads with spaces (Follow-up of #37396) (#44745)
Fix multi-select behavior in Media Manager (Follow-up of #39824) (#44747)
Fix error handling when creating folders in Media Manager (#39878)
Fix assets for com_scheduler on new installations (#44684)
Fix password reset broken in backend (#44723)
Email cloak plugin fails for emails with IDN (Internationalized Domain Names) (#39888)
Fix handling of root path removal only when it is at the beginning (#36685)
Load the namespace from the cached manifest (Reverted) (#44755)
Fix for Codemirror duplicated assets entries (#44674)

The full list on GitHub is here: https://github.com/joomla/joomla-cms/milestone/136?closed=1

Joomla tip: show notifications by Joomla.renderMessages

Sergey Tolkachyov — Mon, 17 Feb 2025 13:49:06 +0000

The user performs some actions on the site and receives messages about the successful or unsuccessful result, as well as just informational messages. In php code, we are used to using the enqueueMessage() method for this.

<?php
use Joomla\CMS\Factory;

$html = 'Message';
Factory::getApplication()->enqueueMessage($html, 'warning');

Most often, language constants are used as messages so that users can receive messages in their own language:

<?php
use Joomla\CMS\Factory;
use Joomla\CMS\Language\Text;

Factory::getApplication()->enqueueMessage(Text::_('SOME_LANG_CONSTANT'), 'info');

Rendering of Joomla messages in the frontend

Here we will need the connected core files core.js and messages.js. A little excerpt from the code:

/**
 * Render messages send via JSON
 * Used by some javascripts such as validate.js
 *
 * @param   {object}  messages JavaScript object containing the messages to render.
 *          Example:
 *          const messages = {
 *              "message": ["This will be a green message", "So will this"],
 *              "error": ["This will be a red message", "So will this"],
 *              "info": ["This will be a blue message", "So will this"],
 *              "notice": ["This will be same as info message", "So will this"],
 *              "warning": ["This will be a orange message", "So will this"],
 *              "my_custom_type": ["This will be same as info message", "So will this"]
 *          };
 * @param  {string} selector The selector of the container where the message will be rendered
 * @param  {bool}   keepOld  If we shall discard old messages
 * @param  {int}    timeout  The milliseconds before the message self destruct
 * @return  void
 */

This is what it looks like in practice:

Joomla.renderMessages({
    message: [Joomla.Text._('COM_SWJPROJECTS_USER_KEYS_KEY_SUCCESSFULLY_COPYED')]
});

Now we see that we can use language constants as a message in Javascript. And that's cool! To do this, we use the Joomla.Text._() method (similar to Text::_() in PHP). But Javascript has to get the values of these language constants from somewhere. And to do this, in the php code of our page, we need to take care of it and add the language constants necessary for js using the Text::script() method.

<?php
use Joomla\CMS\Language\Text;

Text::script('SOME_LANG_CONSTANT_SUCCESS');
Text::script('SOME_LANG_CONSTANT_FAIL');

This way I can access the values of the language constants SOME_LANG_CONSTANT_SUCCESS and SOME_LANG_CONSTANT_FAIL in javascript.

Joomla Community resources

Joomla tip: Use the Joomla\Uri\Uri class to create a URL.

Sergey Tolkachyov — Thu, 16 Jan 2025 11:15:47 +0000

When building a url in the code, you can collect all the strings with concatenation of the form

$url = $domain.'/index.php?option='.$option.'&view='.$view.'&param1='.$value1;

and for small strings, it can even be convenient. But if there are a lot of parameters or they require standardization/cleaning in the process, then not everything is so convenient and obvious. For example, there may be a leading slash in part of the url (a slash at the beginning of the url fragment) and the incoming domain for the request may also end in a slash, and so we get an incorrect url for the request with a double slash somewhere in the middle...

For the tasks of standardization and uniformity of url retrieval, Joomla has the Joomla\Uri\Uri class. Previously, with Joomla 1.6 and older, it was called JUri. This class provides work with urls according to the RFC3986 standard and takes over the work of parsing URLs for spare parts or assembling URLs from spare parts))

Example: get a specific parameter from the url.

use Joomla\Uri\Uri;

$url = 'https://web-tolk.ru/dev/biblioteki?param=value';
$uri = new Uri($url);
// output the line 'value' here
echo $uri->getVar('param');

Yes, there is a native PHP function parse_url, you might say... But the Uri class ensures safe operation with UTF-8 in urls, including Cyrillic domains. In order not to write various checks yourself, you can use the features of the Joomla core.

How to build required url in the code in Joomla

Here, too, everything is simple:

use Joomla\Uri\Uri;

$uri = new Uri;
$uri->setHost('web-tolk.ru');
$uri->setScheme('https');
// setPath() starts with leading slash
$uri->setPath('/dev/biblioteki');
// GET-parameters can be passed as an array
$vars = [
        'param1' => 'value1',
        'param2' => 'value2',
        'param3' => 'value3',
];
$uri->setQuery($vars);
// echo our url like string
echo $uri->toString();

The hierarchy of Uri classes in Joomla is designed so that getter methods are in the AbstractUri class, and setters are in the Uri class. The setters can be viewed in the file libraries/vendor/joomla/uri/src/Uri.php . We look at Hetaera in the file libraries/vendor/joomla/uri/src/AbstractUri.php.

If you have PHPStorm, then it knows Joomla perfectly well and tells you everything you need.
Well, you can give a link to the old documentation page, which is still mostly relevant, adjusted for the use of namespaces.

Uri structure:

     foo://example.com:8042/over/there?name=ferret#nose
     \_/   \______________/\_________/ \_________/ \__/
      |           |            |            |        |
   scheme     authority       path        query   fragment

Joomla Community resources

The anatomy of smart search in Joomla 5. Creating a plugin Part 3

Sergey Tolkachyov — Fri, 03 Jan 2025 06:29:11 +0000

In the first article, we got acquainted with the capabilities of the Joomla smart search component, talked about the parameters and configuration of scheduled indexing using CRON. And in the second article we've started to code our custom plugin for Joomla smart search component. So, let's finish it!

The index() method

This method should adapt the data obtained from the database in order to submit it for indexing. As an argument, the $item element (article, product, tag, etc.) is passed to it as an instance class of the \Joomla\Component\Finder\Administrator\Indexer\Result class. The properties of $item match those that we selected from the database. The ultimate goal of this method is to call $this->indexer->index($item).

You need to understand what the search results will look like in order to understand what to compare with what.

Joomla 5 smart search result structure

Here I take the names straight from the code. In this case, the images are not shown in the search results, but they are also there - $this->result->imageUrl.

imageUrl - a picture of the Joomla article, product, tag, contact. It is displayed if enabled in the settings of the smart search component.
title - the title of the material, the name of the product, contact, etc.
description and body - a text description. We remember that many entities in Joomla have a short and complete description or an introductory and full text. Here they are combined and then trimmed to the character limit specified in the settings. body is the full text or description.
getTaxonomy() - the method receives and outputs taxonomy data for a given search result.

Thus, we have few data visible to the user - only 4 types. And we get more data from the database. We need to understand which of them will be available for indexing by search, and which will only be displayed.

Here is the code of the index() method with comments.

<?php
/**
 * Method to index an item. The item must be a Result object.
 *
 * @param   Result  $item  The item to index as a Result object.
 *
 * @return  void
 *     
 * @throws  \Exception on database error.
 * @since   2.5
 */
protected function index(Result $item)
{
    // Setting the language of the indexed element - the default language of the site
    $item->setLanguage();
    // Check if JoomShopping is enabled in Joomla.
    if (ComponentHelper::isEnabled($this->extension) === false)
    {
        return;
    }
    // We take part of the paths to the pictures from the component parameters.
    $this->loadJshopConfig();
    // Setting the context for indexing
    $item->context = 'com_jshopping.product';

    // We collect all the parameters in a bunch: the search component, JoomShopping and the site.
    // They will be available to us in the output layout
    $registry     = new Registry($item->params);
    $item->params = clone ComponentHelper::getParams('com_jshopping', true);
    $item->params->merge($registry);
    $item->params->merge((new Registry($this->jshopConfig)));
    // Meta-data: meta-keywords, meta description, author,
    // index / no-index values for robots
    $item->metadata = new Registry($item->metadata);

    // Process the content with content plugins - the onContentPrepare event.
    // Content plugins always have a context check.
    // If it is equal to 'com_finder.indexer', then content plugins will usually not work.
    // ONLY TEXT should be given for indexing.
    // Neither pictures nor YouTube videos should get there, so
    // the indexed content will be cleared of HTML tags.
    // The raw short codes are just text and can get
    // into the search results.

    $item->summary = Helper::prepareContent($item->summary, $item->params, $item);
    $item->body    = Helper::prepareContent($item->body, $item->params, $item);
    // Include here JoomShopping classed.
    require_once JPATH_SITE . '/components/com_jshopping/bootstrap.php';
    \JSFactory::loadAdminLanguageFile($this->languageTag, true);

    //
    // A trick. We want to be able to search by price, product code, etc too.
    // Attaching all this data to the body.
    //

    // Manufacturer code
    $manufacturer_code = $item->getElement('manufacturer_code');
    if (!empty($manufacturer_code))
    {
        $item->body .= ' ' . Text::_('JSHOP_MANUFACTURER_CODE') . ': ' . $manufacturer_code;
    }

    // EAN
    $product_ean = $item->getElement('product_ean');
    if (!empty($product_ean))
    {
        $item->body .= ' ' . Text::_('JSHOP_EAN') . ': ' . $product_ean;
    }

    // Old price
    $product_old_price = (float) $item->getElement('product_old_price');
    if (!empty($product_old_price))
    {
        $product_old_price = \JSHElper::formatPrice($item->getElement('product_old_price'));
        $item->body        .= ' ' . Text::_('JSHOP_OLD_PRICE') . ': ' . $product_old_price;
    }

    // Buy price
    $product_buy_price = (float) $item->getElement('product_buy_price');
    if (!empty($product_buy_price))
    {
        $product_buy_price = \JSHElper::formatPrice($item->getElement('product_buy_price'));
        $item->body        .= ' ' . Text::_('JSHOP_PRODUCT_BUY_PRICE') . ': ' . $product_buy_price;
    }
    // Price
    $product_price = (float) $item->getElement('product_price');
    if (!empty($product_price))
    {
        $product_price = \JSHElper::formatPrice($product_price);
        $item->body    .= ' ' . Text::_('JSHOP_PRODUCT_PRICE') . ': ' . $product_price;
    }


    // URL - the unique key of the element in the table. Read more about this after the sample code
    $item->url = $this->getUrl($item->slug, 'com_jshopping', $item->catslug);

    // Link to element - to JoomShopping product
    $item->route = $item->url;

    // A menu item can be created for product. Menu item has own page header.
    // Joomla menu has higher priority then we'll take data from it.
    $title = $this->getItemMenuTitle($item->url);

    // Adjust the title if necessary.
    if (!empty($title) && $this->params->get('use_menu_title', true))
    {
        $item->title = $title;
    }

    // Add product image
    $product_image = $item->getElement('image');
    if (!empty($product_image))
    {
        $item->imageUrl = $item->params->get('image_product_live_path') . '/' . $product_image;
        $item->imageAlt = $item->title;
    }

    // The product has no author. But you can do this if you search by author/user
    // For example, you enabled search by author in the smart search component settings
    // and it should search for everything related to this author
    // $item->metaauthor = $item->metadata->get('author');

    // Add the metadata processing instructions.
    $item->addInstruction(Indexer::META_CONTEXT, 'metakey');
    $item->addInstruction(Indexer::META_CONTEXT, 'metadesc');
    // $item->addInstruction(Indexer::META_COTNTEXT, 'metaauthor');
    // $item->addInstruction(Indexer::META_CONTEXT, 'author');
    // $item->addInstruction(Indexer::META_CONTEXT, 'created_by_alias');

    // Access group for the default search result.
    // We hardcode "1" - that is, for everyone. But here you can
    // take the access group from the product.
    // Or show different search results to different access groups.
    $item->access = 1;

    // Check if the category for the product is published.
    // Products should only be published if their category is published.
    $item->state = $this->translateState($item->state, $item->cat_state);

    // Get the list of taxonomies to display from the plugin parameters
    $taxonomies = $this->params->get('taxonomies', ['product', 'category', 'language']);
    // Name of the search type in the drop-down list of types: materials, contacts.
    // In our case - product. We take a language constant for this.
    $item->addTaxonomy('Type', Text::_('JSHOP_PRODUCT'));
    // Add product categories to the drop-down list
    // categories so that you can search only in a specific
    // categories. Here we already transfer the names of the categories.
    $item->addTaxonomy('Category', $item->category);
    // Search only in the desired language
    $item->addTaxonomy('Language', $this->getLangTag());
    // Search results can be limited by publication start and end dates
    $item->publish_start_date = Factory::getDate()->toSql();
    $item->start_date         = Factory::getDate()->toSql();

    // Add additional data for the indexed element.
    // Here in the helper the "onPrepareFinderContent" event is called
    // This is usually how comments, tags, labels
    // and other things that should be available for search are added.
    // Accordingly, individual plugins work with this event.
    // In our case, we do not need this yet.
    // Helper::getContentExtras($item);

    // Add custom fields (com_fields) Joomla, if the component
    // supports them.
    // In our case, we do not need this yet.
    // Helper::addCustomFields($item, 'com_jshopping.product');

    // Index the item.
    $this->indexer->index($item);
}

Types of instructions for "marking up the weight" of content for indexing.

I am not an expert in fine-tuning indexing, so I will try to describe what I could see in the code. In the parameters of the smart search component, there are weight settings for each part of the indexed content: title, main text, metadata, url, additional text.

Joomla 5 smart search params - indexing weight settings for title, body, metadata

We have already seen these settings above in the first article in seria, but for convenience we will repeat the screenshot.

In our smart search plugin, we can specify which data in our object for indexing belongs to which type by adding instructions:

<?php
// In the index() method
$item->addInstruction(Indexer::TEXT_CONTEXT, 'product_buy_price');

We look at the types of context for instructions and their names by default in the class \Joomla\Component\Finder\Administrator\Indexer\Result.

Joomla smart search indexing instructions types for weight markup

As I later found out, list_price and sale_price refer to indexing, not to the terminology of an online store.

getUrl() method

The unique key for searching is essentially the url of the element in its system form: index.php?option=com_content&view=article&id=1. In the database in the #__finder_links table, it is stored in the url column. But to build a link in the frontend to the desired element from the search results, a more complex option is used with a combination of id and aliases in the url: index.php?option=com_content&view=article&id=1:article-alias&catid=2, which is stored in the adjacent route column. But Joomla routing will determine the final url without specifying an alias, in which case the content of the url and route will be the same.

<?php
// Fragment of index() method of smart search plugin for Joomla materials

// Create a URL as identifier to recognise items again.
$item->url = $this->getUrl($item->id, $this->extension, $this->layout);

// Build the necessary route and path information.
$item->route = RouteHelper::getArticleRoute($item->slug, $item->catid, $item->language);

The system url for the indexed element looks different in different components. In the components that follow the "Joomla way", you can use one controller, which, if no specific controller is found, will immediately show the desired View. Therefore, in standard Joomla components, we usually do not find links indicating the controller in the GET parameters. They will all look like index.php?option=com_content&view=article&id=15. This is the url that the getUrl() method of the Adapter class returns to us.

<?php
/**
 * Method to get the URL for the item. The URL is how we look up the link
 * in the Finder index.
 *
 * @param   integer  $id         The id of the item.
 * @param   string   $extension  The extension the category is in.
 * @param   string   $view       The view for the URL.
 *
 * @return  string  The URL of the item.
 *
 * @since   2.5
 */
protected function getUrl($id, $extension, $view)
{
    return 'index.php?option=' . $extension . '&view=' . $view . '&id=' . $id;
}

However, JoomShopping has its own story and URLs are built somewhat differently. We will not be able to use the standard method and we are redefining it.

<?php
use Joomla\CMS\Uri\Uri;

/**
 * @param string $product_id  Product id
 * @param string $extension  Always 'com_jshopping'
 * @param string $view  Not used for JoomShopping
 *
 * @return string
 *
 * @since 1.0.0
 */
public function getUrl($product_id, $extension, $view = 'not_used') : string
{
    /**
     * There is the trick. For JoomShopping product url construction
     * we need only in product id and category id
     */
    $this->loadJshopConfig();
    // Keeping in mind the difficulties with categories in JoomShopping
    // we separate the process of getting the category into a separate method.
    $category_id = $this->getProductCategoryId((int)$product_id);
    $url = new Uri();
    $url->setPath('index.php');
    $url->setQuery([
        'option'      => 'com_jshopping',
        'controller'  => 'product',
        'task'        => 'view',
        'category_id' => $category_id,
        'product_id'  => $product_id,
    ]);
    // When constructing a url in JoomShopping, it is advisable to find and specify
    // The correct itemId is the id of the menu item for JoomShopping.
    // Otherwise, we may have duplicate pages by url
    // We connected the JoomShopping API earlier, so the JSHelper should already be here.
    $defaultItemid = \JSHelper::getDefaultItemid($url->toString());
    $url->setVar('Itemid', $defaultItemid);

    return $url->toString();
}

An atypical implementation of multilingualism. Indexation.

Let's return to the problem of multilingualism, in which we do not have a separate indexed entity for each content language. But there is an indexed entity that contains values for all languages at once.

The solution is to get a list of all languages inside the index() method, collect the Result object for each language and then give each object for indexing. We need to divide the data into those that are the same for both languages (usually catid, access, etc.) and different (title, description, fulltext etc.). That is, the $this->indexer->index() method will be called several times inside the Index() method of our plugin.

<?php
/**
 * Method to index an item. The item must be a Result object.
 *
 * @param   Result  $item  The item to index as a Result object.
 *
 * @return  void
 *
 * @throws  \Exception on database error.
 * @since   2.5
 */
protected function index(Result $item)
{

    // Initialise the item parameters.
    $registry     = new Registry($item->params);
    $item->params = clone ComponentHelper::getParams('com_swjprojects', true);
    $item->params->merge($registry);
    $item->context = 'com_swjprojects.project';
    $lang_codes    = LanguageHelper::getLanguages('lang_code');

    $translates = $this->getTranslateProjects($item->id, $item->catid);

    // Translate the state. projects should only be published if the category is published.
    $item->state = $this->translateState($item->state, $item->cat_state);

    // Get taxonomies to display
    $taxonomies = $this->params->get('taxonomies', ['type', 'category', 'language']);

    // Add the type taxonomy data.
    if (\in_array('type', $taxonomies))
    {
        $item->addTaxonomy('Type', 'Project');
    }

    $item->access = 1;
    foreach ($translates as $translate)
    {
        $item->language = $translate->language;
        $item->title    = $translate->title;
        // Trigger the onContentPrepare event.
        $item->summary = Helper::prepareContent($translate->introtext, $item->params, $item);
        $item->body    = Helper::prepareContent($translate->fulltext, $item->params, $item);

        $metadata       = new Registry($translate->metadata);
        $item->metakey  = $metadata->get('keywords', '');
        $item->metadesc = $metadata->get('description', $translate->introtext);
        // Add the metadata processing instructions.
        $item->addInstruction(Indexer::META_CONTEXT, 'metakey');
        $item->addInstruction(Indexer::META_CONTEXT, 'metadesc');

        $lang = '';

        if (Multilanguage::isEnabled())
        {
            foreach ($lang_codes as $lang_code)
            {
                if ($translate->language == $lang_code->lang_code)
                {
                    $lang = $lang_code->sef;
                }
            }
        }
        // Create a URL as identifier to recognise items again.
        $item->url = $this->getUrl($item->id, $this->extension, $this->layout, $lang);

        // Build the necessary route and path information.
        $item->route = RouteHelper::getProjectRoute($item->id, $item->catid);

        // Get the menu title if it exists.
        $title = $this->getItemMenuTitle($item->route);

        // Adjust the title if necessary.
        if (!empty($title) && $this->params->get('use_menu_title', true))
        {
            $item->title = $title;
        }

        // Add the category taxonomy data.
        if (\in_array('category', $taxonomies))
        {
            $item->addTaxonomy('Category', $translate->category, 1, 1, $item->language);
        }

        // Add the language taxonomy data.
        if (\in_array('language', $taxonomies))
        {
            $item->addTaxonomy('Language', $item->language, 1, 1, $item->language);
        }


        $item->metadata = new Registry($item->metadata);

        $icon = ImagesHelper::getImage('projects', $item->id, 'icon', $item->language);

        // Add the image.
        if (!empty($icon))
        {
            $item->imageUrl = $icon;
            $item->imageAlt = $item->title;
        }

        // Add the meta author.
        // $item->metaauthor = $item->metadata->get('author');

        // Get content extras.
        // Helper::getContentExtras($item);
        // Helper::addCustomFields($item, 'com_swjprojects.project');

        // Index the item.
        $this->indexer->index($item);
    }
}

We also need to unify the value for the route field for each language, so we make our own implementation of the getUrl() method and add the $lang parameter to the url.

<?php
/**
 * @param   int     $id
 * @param   string  $extension
 * @param   string  $view
 * @param   string  $lang  Language SEF code like `ru`, `en` etc
 *
 * @return string
 *
 * @since 2.1.0
 */
public function getUrl($id, $extension, $view, $lang = '')
{
    $url = 'index.php?option=' . $extension . '&view=' . $view . '&id=' . $id;

    if (!empty($lang))
    {
        $url .= '&lang=' . $lang;
    }

    return $url;
}

getItems() and getContentCount() methods

In general, we don't need anything else for manual indexing and reindexing of content, as well as scheduled via the CLI. However, if we come across some very unusual beast in the form of non-Joomla data, some third-party database, then we can completely redefine the logic of the parent Adapter class for these purposes.

getContentCount() - the method should return an integer - the number of indexed elements.
getItems($offset, $limit, $query = null) - under the hood, calls getListQuery() and sets $offset and $limit, brings everything to a single view - objects.

If using one getListQuery() method and accessing it from 3 other methods is inconvenient for some reason, you can customize requests and their processing in redefined methods.

Reindexing content on the fly

To solve this problem, we have several ways, two of which are the periodic manual and CRON indexing, as I wrote above. However, this is fraught with an untimely index update and site users may not receive updated data in search results on time. Therefore, there is another way: reindexing the content on the fly, immediately after saving the changes. To do this, a content group plugin is created, which triggers smart search plugin events at the right moments.

Content plugin for joomla smart search

Standard Joomla Model Events.
If the component is written according to the canons of Joomla and inherits its classes, then many models (Model - MVC) trigger standard events, among which we are interested in several:
onContentBeforeSave - The event is triggered before any Joomla entity is saved.

onContentAfterSave - The event is triggered after saving any Joomla entity.
onContentAfterDelete - The event is triggered after deleting any Joomla entity.
onContentChangeState - the event is triggered after a state change (unpublished/published).
onCategoryChangeState - The event is triggered after the category status changes (if the standard Joomla categories component is used).

By default, the smart search plugin causes the content to be reindexed at the listed points in time. In each of these events, the context of the event call is passed in the form of <component>.<entity>, for example, com_content.article or com_menus.menu. According to the desired context, you can determine whether to start reindexing or not. We are already doing this check in the smart search plugin. An example from the code of the Finder content plugin for Joomla articles:

<?php
use Joomla\CMS\Event\Finder as FinderEvent;

/**
 * Smart Search after save content method.
 * Content is passed by reference, but after the save, so no changes will be saved.
 * Method is called right after the content is saved.
 *
 * @param   string  $context  The context of the content passed to the plugin (added in 1.6)
 * @param   object  $article  A \Joomla\CMS\Table\Table\ object
 * @param   bool    $isNew    If the content has just been created
 *
 * @return  void
 *
 * @since   2.5
 */
public function onContentAfterSave($context, $article, $isNew): void
{
    $this->importFinderPlugins();

    // Trigger the onFinderAfterSave event.
    $this->getDispatcher()->dispatch('onFinderAfterSave', new FinderEvent\AfterSaveEvent('onFinderAfterSave', [
        'context' => $context,
        'subject' => $article,
        'isNew'   => $isNew,
    ]));
}

As we can see, the onFinderAfterSave event is called here, which is specific specifically for smart search plugins. And in the onFinderAfterSave() method of our smart search plugin, there is already a check for the desired context and reindexing.

<?php
use Joomla\CMS\Event\Finder as FinderEvent;

/**
 * Smart Search after save content method.
 * Reindexes the link information for an article that has been saved.
 * It also makes adjustments if the access level of an item or the
 * category to which it belongs has changed.
 *
 * @param   FinderEvent\AfterSaveEvent   $event  The event instance.
 *
 * @return  void
 *
 * @since   2.5
 * @throws  \Exception on database error.
 */
public function onFinderAfterSave(FinderEvent\AfterSaveEvent $event): void
{
    $context = $event->getContext();
    $row     = $event->getItem();
    $isNew   = $event->getIsNew();

    // We only want to handle articles here.
    if ($context === 'com_content.article' || $context === 'com_content.form') {
        // Check if the access levels are different.
        if (!$isNew && $this->old_access != $row->access) {
            // Process the change.
            $this->itemAccessChange($row);
        }

        // Reindex the item.
        $this->reindex($row->id);
    }

    // Check for access changes in the category.
    if ($context === 'com_categories.category') {
        // Check if the access levels are different.
        if (!$isNew && $this->old_cataccess != $row->access) {
            $this->categoryAccessChange($row);
        }
    }
}

In the same way, the work is organized when the state changes and the article or product is deleted.

getItem() method

This method gets the indexed element by its id. It is called when reindexing after saving articles, products, etc. - on the onFinderAfterSave event. Internally, it receives an SQL query from the getListQuery() method, adds the id of the requested entity to it, and executes the query. However, in the parent class, the id field with the prefix a is hardcoded for tables - $query->where('a.id = ' . (int) $id). Since in our case both the prefix and the name of the field for the request are different, we redefine the method too.

<?php
// I have indicated here only the namespaces used in the example
use Joomla\Utilities\ArrayHelper;
use Joomla\Component\Finder\Administrator\Indexer\Result;

/**
 * Method to get a content item to index.
 *
 * @param   integer  $id  The id of the content item.
 *
 * @return  Result  A Result object.
 *
 * @throws  \Exception on database error.
 * @since   2.5
 */
protected function getItem($id)
{
    // Get the list query and add the extra WHERE clause.
    $query = $this->getListQuery();
    $query->where('prod.product_id = ' . (int) $id);

    // Get the item to index.
    $this->db->setQuery($query);
    $item = $this->db->loadAssoc();

    // Convert the item to a result object.
    $item = ArrayHelper::toObject((array) $item, Result::class);

    // Set the item type.
    $item->type_id = $this->type_id;

    // Set the item layout.
    $item->layout = $this->layout;

    return $item;
}

Conclusion

This articles seria does not pretend to be a complete description of the mechanics of smart search in Joomla, even after 4 months of work on it. And in this case it is not a metaphor. But I hope this article will help those who will take up writing plugins for indexing data from Joomla components or third-party systems.

I will gratefully accept suggestions for improving the article and additions in the comments.

Joomla Community resources

https://joomla.org/
This article in Joomla Community Magazine
Joomla Community chat in Mattermost (read more)

DEV Community: Sergey Tolkachyov

ProcessForge 1.2.0 Released: Performance Optimizations and Improved Reliability

Optimizing Work with Large Volumes of Data

1. Moving Event Journals to SQLite

2. Faster Selection of the Current Work

3. Reusing Parsed YAML

Improved Recovery After Worker Failures

Safely Continuing Work in a New Session

Expanded Capabilities of the ProcessForge MCP Server

Managing Workers

Continuing Work Across Sessions

Searching for Knowledge Within a Work

Discovering Available Commands

Session Management and Message Recording

Why Were These Changes Made?

Clearer Instructions for Agents Entering a Project

Managing Temporary Files

What Does This Mean in Practice?

Process Forge: a framework for creating AI processes

Starting Points

Process Forge Concepts

Process Instead of Chat

Connecting Knowledge to an AI Process

Connecting Tools, MCP, and Templates

Templates

Tools and MCP

Processes Again

Platforms and Specialisations

Platforms

Specialisations

Cascading Project Context Computation

The General Feedback Mechanism: Evolve

Versioning

Organising Work in Process Forge

Garage Mode (1-1-1-1)

Forge / Factory Mode

Conclusion

How to work with the component menu in the Joomla admin panel using preset.xml and the plugin.

CFI Plugin v.2.0.0 Released - Export/Import Joomla Articles to/from CSV

v.2.0.0. What's New?

Joomla View Logs component v.2.3.0 has been released!

v.2.3.0 What's new?

Joomla-дайджест. 2-е полугодие 2025 года.

WT IndexNow - send your Joomla urls to search engines via IndexNow protocol

Supported components

Links

WT Yandex map items v.2.0.5 Joomla module has been released

v.2.0.5. What's new?

UX improving

Joomla 5.2.4 Security & Bugfix Release

Security Fix

Bug fixes and Improvements with 5.2.4

Joomla Community resources

Joomla tip: show notifications by Joomla.renderMessages

Rendering of Joomla messages in the frontend

Joomla Community resources

Joomla tip: Use the Joomla\Uri\Uri class to create a URL.

Example: get a specific parameter from the url.

How to build required url in the code in Joomla

Joomla Community resources

The anatomy of smart search in Joomla 5. Creating a plugin Part 3

The index() method

Types of instructions for "marking up the weight" of content for indexing.

getUrl() method

An atypical implementation of multilingualism. Indexation.

getItems() and getContentCount() methods

Reindexing content on the fly

getItem() method

Conclusion

Joomla Community resources